diff --git a/.agent/CHANGELOG.md b/.agent/CHANGELOG.md new file mode 100644 index 0000000..2e8706c --- /dev/null +++ b/.agent/CHANGELOG.md @@ -0,0 +1,31 @@ +# Changelog + +## 0.2.0 - 2026-05-19 + +### Added + +- Opt-in self-approval and self-merge workflows with reviewed-head provenance, PR-author blocks, status comments, and orchestrator handoffs. +- Repository skill setup hooks through `setup.sh` and a shared skill setup action. +- Upload-only track-only session bundles for debugging one-shot runs without treating them as resumable continuity state. + +### Changed + +- Dispatch and orchestration now recognize orchestrate starts from triage, derive implement tracking metadata from issue context, and carry stacked `base_pr` metadata through router dispatch. +- Onboarding and installation docs now emphasize hosted App prerequisites, reused setup issue status, and simpler first-run guidance. +- Daily summary scheduling and orchestration defaults are more conservative; the packaged daily summary cron remains disabled by default. +- GitHub memory artifacts are namespaced by owner and repo, with legacy artifact cleanup kept explicit. +- Sepo release notes now live in `.agent/CHANGELOG.md` alongside the canonical runtime version in `.agent/package.json`. + +### Fixed + +- Normalized weak GitHub mention associations across triggers and added regression coverage for weak association handling. +- Hardened auto-merge eligibility, self-approval status upserts, and review handoff behavior for current reviewed heads. + +## 0.1.0 - 2026-05-11 + +### Added + +Initial public pre-release of Sepo, a GitHub-native agent harness for orchestrating long-running coding tasks with repository memory through GitHub Actions. It features the following: +- Git-native memory and rubrics layout: code-related memory and induced user/team rubrics live alongside the repository on the `agent/memory` and `agent/rubrics` branches. +- GitHub Actions workflows that can propose code changes, run verification, and execute computational experiments without requiring a separate always-on server. +- Agent orchestration for long-horizon tasks — including task breakdown, review/fix loops, and iterative self-improvement workflows. diff --git a/.agent/action-templates/agent-action-template.yml b/.agent/action-templates/agent-action-template.yml new file mode 100644 index 0000000..ead3a62 --- /dev/null +++ b/.agent/action-templates/agent-action-template.yml @@ -0,0 +1,114 @@ +# Template for generated scheduled agent-action workflows. +# Copy this file to .github/workflows/agent-action-.yml and +# replace the placeholder name, cron, expiration, lane, request text, and +# optional issue-report target. + +name: Agent Action / Example + +on: + schedule: + - cron: "17 * * * *" + workflow_dispatch: + +permissions: + actions: read + contents: read + # If enabling REPORT_ISSUE_NUMBER below, add issue write permission. + id-token: write + +concurrency: + group: agent-action-example-${{ github.repository }} + cancel-in-progress: false + +env: + ACTION_EXPIRES_AT: "YYYY-MM-DD" + REPORT_ISSUE_NUMBER: "" + +jobs: + run: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Check expiration + id: expiration + uses: ./.github/actions/check-agent-action-expiration + with: + expires_at: ${{ env.ACTION_EXPIRES_AT }} + + - name: Resolve GitHub auth + if: steps.expiration.outputs.expired != 'true' + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve provider + if: steps.expiration.outputs.expired != 'true' + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: answer + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + if: steps.expiration.outputs.expired != 'true' + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + if: steps.expiration.outputs.expired != 'true' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run scheduled agent task + if: steps.expiration.outputs.expired != 'true' + id: agent + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: answer + route: answer + lane: agent-action-example + memory_mode_override: read-only + session_policy: track-only + request_text: | + Describe the bounded recurring task here. + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: "0" + target_url: ${{ github.server_url }}/${{ github.repository }} + workflow: agent-action-example.yml + + # Optional: set REPORT_ISSUE_NUMBER and add issue write permission only when the workflow should report to an issue. + - name: Post report to issue + if: >- + steps.expiration.outputs.expired != 'true' && + steps.agent.outcome == 'success' && + env.REPORT_ISSUE_NUMBER != '' + env: + BODY_FILE: ${{ steps.agent.outputs.response_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: issue_comment + TARGET_NUMBER: ${{ env.REPORT_ISSUE_NUMBER }} + run: node .agent/dist/cli/post-response.js diff --git a/.agent/docs/README.md b/.agent/docs/README.md new file mode 100644 index 0000000..814a27e --- /dev/null +++ b/.agent/docs/README.md @@ -0,0 +1,44 @@ +# `.agent` docs + +## Overview + +- [What is a self-evolving repository?](overview/what-is-self-evolving-repo.md) +- [Quick start](overview/quick-start.md) + +## Architecture + +- [Overall design](architecture/overall-design.md) +- [Repository memory](architecture/memory.md) +- [User/team rubrics](architecture/rubrics.md) +- [The life cycle of an agent request](architecture/request-lifecycle.md) +- [Supported workflows](architecture/supported-workflows.md) + +## Technical details + +- [Key concepts](technical-details/key-concepts.md) +- [Session continuity](technical-details/session-continuity.md) +- [Agent orchestrator](technical-details/agent-orchestrator.md) +- [Sepo versioning](technical-details/versioning.md) +- [Developer notes](technical-details/developer-notes.md) + +## Actions + +- [Actions overview](actions/README.md) +- [Internal actions](actions/internal-actions.md) +- [Agent actions](actions/agent-actions.md) + +## Customization + +- [Configurations list](customization/configuration-list.md) +- [Repository skills](customization/skills.md) +- [Trigger access policy](access-policy.md) +- [Creating your own actions](customization/creating-your-own-actions.md) +- [Creating your own workflows](customization/creating-your-own-workflows.md) + +## Deployment + +- [Deployment overview](deployment/README.md) +- [Setup guide](deployment/setup-guide.md) +- [Install into an existing repository](deployment/install-existing-repository.md) +- [Self-hosted GitHub Action runner](deployment/self-hosted-github-action-runner.md) +- [Using your own GitHub App](deployment/using-your-own-github-app.md) diff --git a/.agent/docs/access-policy.md b/.agent/docs/access-policy.md new file mode 100644 index 0000000..cc101c9 --- /dev/null +++ b/.agent/docs/access-policy.md @@ -0,0 +1,84 @@ +# Trigger access policy + +`AGENT_ACCESS_POLICY` is an optional repository variable that controls which GitHub author associations can trigger the agent. + +## Policy shape + +Use `allowed_associations` as the default allowlist for routes without a more specific rule: + +```json +{ + "allowed_associations": ["OWNER", "MEMBER", "COLLABORATOR"] +} +``` + +Add `route_overrides` only when a route needs a narrower or wider allowlist than the default: + +```json +{ + "allowed_associations": ["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR"], + "route_overrides": { + "implement": ["OWNER", "MEMBER"] + } +} +``` + +Both keys are optional: + +- `allowed_associations`: fallback allowlist for routes without an override +- `route_overrides`: map of route name to route-specific allowlist + +Route override keys are matched after route resolution, so future routes can use the same policy shape without changing this schema. If a route has no override, it uses `allowed_associations`; if `allowed_associations` is also unset, it uses the repository visibility default below. + +## Example + +This policy lets contributors ask questions through the default `answer` behavior, while keeping implementation work limited to owners and organization members: + +```json +{ + "allowed_associations": ["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR"], + "route_overrides": { + "implement": ["OWNER", "MEMBER"] + } +} +``` + +## GitHub author associations + +The values match GitHub's [`CommentAuthorAssociation`](https://docs.github.com/graphql/reference/enums#commentauthorassociation) enum: + +- `OWNER` +- `MEMBER` +- `COLLABORATOR` +- `CONTRIBUTOR` +- `FIRST_TIME_CONTRIBUTOR` +- `FIRST_TIMER` +- `MANNEQUIN` +- `NONE` + +## Default behavior + +If `AGENT_ACCESS_POLICY` is unset: + +- private repositories allow `OWNER`, `MEMBER`, `COLLABORATOR`, and `CONTRIBUTOR` +- public repositories also allow `OWNER`, `MEMBER`, `COLLABORATOR`, and `CONTRIBUTOR` + +Known limitation: GitHub can report private organization members as `CONTRIBUTOR` in public repository issue payloads when the token or payload cannot see private membership. Sepo therefore includes `CONTRIBUTOR` in the public default allowlist as a pragmatic compatibility choice. Repositories that need stricter public access should set `AGENT_ACCESS_POLICY`, for example `{"allowed_associations":["OWNER","MEMBER","COLLABORATOR"]}`. + +## Enforcement model + +For mention and label triggers, trigger extraction validates the event, resolves explicit routes or labels when present, and records the caller association. Route authorization happens during dispatch resolution after explicit routes are normalized locally or implicit mentions are triaged into a concrete route. + +That means `route_overrides` also apply to plain implicit mentions such as `@sepo-agent can you help?`. If the resolved route is not allowed, the router posts an inline unsupported reply instead of silently dropping the request. + +Approval comments use the same policy after the pending request is found. The approval check uses the route stored in the pending request marker. + +Label triggers authorize the label applier rather than the issue or pull request author. Personal-repository owners map to `OWNER`; visible organization members map to `MEMBER`; repository collaborators with label permission map to `COLLABORATOR`. After a label-triggered request is accepted by the router, `agent-label.yml` removes the triggering `agent/*` label even when the route is denied, so unauthorized queue labels do not linger. + +Organization membership detection depends on what the agent's GitHub token can see. With a repo-scoped installation token, only **public** org memberships are visible, so private org members who apply a label resolve as `COLLABORATOR` rather than `MEMBER`. Policies that restrict a route to `MEMBER` only (e.g. `route_overrides.implement: ["OWNER", "MEMBER"]`) may therefore reject private org members unless `COLLABORATOR` is also included. + +## Weak association normalization + +For mention triggers, the runtime trusts strong `author_association` values (`OWNER`, `MEMBER`, and `COLLABORATOR`) without another lookup. When GitHub reports a weaker value such as `NONE`, `CONTRIBUTOR`, `FIRST_TIMER`, or `FIRST_TIME_CONTRIBUTOR`, Sepo checks the triggering actor with `GET /repos/{owner}/{repo}/collaborators/{username}` and treats a `204` response as `COLLABORATOR` before route authorization. This applies to all supported mention surfaces, including issue and pull request bodies, discussion bodies and comments, issue comments, pull request review comments, and pull request reviews. + +Issue-body mentions from `issues` events also refresh `author_association` from the live issue API before the collaborator fallback. These checks cover cases where repo-scoped tokens cannot see private org membership through webhook `author_association`, but GitHub author association remains token- and visibility-dependent. The public default allowlist therefore still includes `CONTRIBUTOR` unless a repository configures a stricter `AGENT_ACCESS_POLICY`. diff --git a/.agent/docs/actions/README.md b/.agent/docs/actions/README.md new file mode 100644 index 0000000..7fd16f9 --- /dev/null +++ b/.agent/docs/actions/README.md @@ -0,0 +1,20 @@ +# Actions + +This section documents the action layer inside the `.agent` backend. + +The docs use three terms consistently: + +- **Workflows** are GitHub workflow files in `.github/workflows/`. They define triggers, jobs, permissions, and dispatch boundaries. See [Supported workflows](../architecture/supported-workflows.md). +- **Internal actions** are shared composite GitHub Actions in `.github/actions/`. They scaffold the runtime, resolve GitHub auth, and run agent tasks for workflows. +- **Agent actions** are route-level behaviors such as `answer`, `implement`, `fix-pr`, and `review`. They are selected by mention, label, approval, or workflow dispatch, and are implemented through workflow wiring plus prompts. + +## Documentation model + +These pages are hand-written for now. The desired long-term pattern is to keep small `agent-doc` metadata blocks near the YAML workflows, composite actions, and prompt files, then render this section from that metadata. + +Until that renderer exists: + +- [Internal actions](internal-actions.md) is the canonical place for `.github/actions/*` details. +- [Agent actions](agent-actions.md) is the canonical place for route behavior, prompt consumption, session policy, and generated-doc metadata conventions. + +Avoid duplicating internal action details in setup or architecture pages. Those pages should explain user-facing behavior and link here for implementation details. diff --git a/.agent/docs/actions/agent-actions.md b/.agent/docs/actions/agent-actions.md new file mode 100644 index 0000000..8a0c444 --- /dev/null +++ b/.agent/docs/actions/agent-actions.md @@ -0,0 +1,131 @@ +# Agent actions + +Agent actions are route-level behaviors exposed by the `.agent` backend. They are selected by the router from mentions, labels, approval comments, or direct workflow dispatch. + +| Agent action | Route | Typical prompt or skill source | Execution path | +|---|---|---|---| +| Answer | `answer` | `.github/prompts/agent-answer.md` | inline response through `agent-router.yml` | +| Implement | `implement` | `.github/prompts/agent-implement.md` | explicit `/implement` or `agent/implement` label dispatches `agent-implement.yml` directly; triaged implement goes through approval first | +| Fix PR | `fix-pr` | `.github/prompts/agent-fix-pr.md` | PR-only dispatch to `agent-fix-pr.yml` | +| Review | `review` | `.github/prompts/review.md` and `.github/prompts/review-synthesize.md` | parallel review jobs plus synthesis in `agent-review.yml` | +| Orchestrate | `orchestrate` | `.github/prompts/agent-orchestrator.md` | explicit `/orchestrate`, `agent/orchestrate`, or dispatch-triaged issue/PR requests dispatch `agent-orchestrator.yml`, which selects the next action based on current target state | +| Self approve | `agent-self-approve` | `.github/prompts/agent-self-approve.md` | opt-in PR approval gate in `agent-self-approve.yml`; deterministic code submits approval only after current-head checks pass | +| Self merge | `agent-self-merge` | deterministic resolver | opt-in PR merge gate in `agent-self-merge.yml`; deterministic code merges only after current-head self-approval, checks, mergeability, and requested-change guards pass | +| Create action | `create-action` | `.github/prompts/agent-create-action.md` | implementation PR that adds or updates a standalone scheduled workflow under `.github/workflows/` | +| Skill | `skill` | `//SKILL.md` | inline skill route through `agent-router.yml`; optional `//setup.sh` hook | +| Dispatch | `dispatch` | `.github/prompts/agent-dispatch.md` | route triage inside `agent-router.yml` | + +The orchestrator is now a top-level route. Users start orchestration explicitly with `/orchestrate` or `agent/orchestrate`; dispatch triage can also select `orchestrate` for issue and pull request requests that ask for orchestration, follow-up automation, or bounded multi-step agent work. `agent-orchestrator.yml` chooses follow-up work from current target state. Workflows launched by the orchestrator carry explicit orchestration context and hand back after post-processing, so the bounded `implement -> review -> fix-pr -> review` loop can continue until a stop condition. Direct `/implement`, `/review`, and `/fix-pr` runs do not carry that context and stay one-shot. In `heuristics` mode, PR orchestrate starts use deterministic status routing. In `agent` mode, issue and PR orchestrate starts invoke the planner. For small self-contained issue work, the planner can hand off directly to `implement` on the current issue. For PR work, the planner can choose `review`, `fix-pr`, `answer`, or stop/block; runtime policy validates that PR starts dispatch only `review` or `fix-pr`. For meta-orchestration, child work uses the internal `delegate_issue` decision to create, reuse, or adopt a child issue that then runs the normal `/orchestrate` flow. `delegate_issue` is not a public route and is not part of `AgentAction`. Planner handoffs can carry `handoff_context`; `fix-pr` receives that context as explicit initial steering for the automated fix pass. + +Implementation runs can create stacked PRs by receiving either `base_branch` or +`base_pr`. `base_pr` resolves to the open same-repository PR head branch; when +neither input is set, implementations branch from the repository default branch. +For explicit `/implement` requests on pull requests, the router can obtain +`base_pr` from the metadata-only tracking issue prompt when the current request +asks for stacked or follow-up implementation work. + +## Consumption model + +Agent actions share the same runtime shape: + +1. A trigger enters a workflow and converges on `agent-router.yml` or a route-specific workflow. +2. The route chooses a prompt name or skill name. +3. `.github/actions/run-agent-task` builds a runtime envelope with route, target, source, request, lane, and session-policy metadata. +4. The runtime prepends `.github/prompts/_base.md` to the selected prompt, substitutes prompt variables, and runs the selected `acpx` agent. +5. Post-processing steps parse the response, post comments, create branches, create PRs, or update the existing PR branch depending on the route. + +The shared base prompt defines the common metadata and context-gathering contract. Route prompts should focus on route-specific behavior and should not duplicate the base metadata header. + +## Scheduled action workflows + +Durable actions are repository-owned GitHub Actions workflows under +`.github/workflows/`. They are proposed through normal implementation pull +requests, reviewed by humans, and only become runnable after merge to the default +branch. + +The `create-action` route creates or updates one standalone workflow, usually +named `agent-action-.yml`. Generated workflows use native +`schedule`/`workflow_dispatch` triggers and the existing shared runtime actions +(`resolve-github-auth`, `resolve-agent-provider`, `setup-agent-runtime`, and +`run-agent-task`). GitHub does not expire scheduled workflows automatically, so +generated scheduled workflows use `.github/actions/check-agent-action-expiration` +and skip provider setup/agent execution once expired. + +The built-in `agent-update.yml` workflow is the default recurring maintenance +path for Sepo itself. It runs near-biweekly, resolves the update source to the +latest published stable Sepo release tag, calls the existing `update-agent` +skill, and opens an update PR only when the target repository differs from that +source. Manual dispatch can pass `source_ref` to test `main`, a branch, or a +specific tag. If no release exists yet, the workflow falls back to `main` and +records that fallback in the run summary. A pre-runtime pending-PR resolver +adopts an open same-repository `agent/update-agent-infra-*` PR by preparing its +branch as the update target while keeping workflow runtime code on the default +branch, then instructing the update skill to update that PR instead of opening a +duplicate. Set `AGENT_AUTO_UPDATE=false` to disable scheduled update checks +while keeping manual dispatch available; the canonical `self-evolving/repo` +source repository should use that setting instead of relying on a workflow-level +repository special case. + +## Self-documenting pattern + +The desired source of truth for generated agent-action docs is a pair of small metadata blocks: one near the workflow wiring and one near the prompt. + +Workflow metadata should describe routing, execution, and session behavior: + +```yaml +# agent-doc: +# kind: agent-action +# action: implement +# title: Implement +# route: implement +# summary: Creates a branch, commits approved changes, and opens a draft PR. +# workflow: .github/workflows/agent-implement.yml +# prompt: .github/prompts/agent-implement.md +# session_policy: track-only +# lane: default +# dispatch: +# trigger: approval +# approval_required: true +# post_processing: +# - verify changes +# - parse structured response +# - commit and push +# - create pull request +``` + +Prompt metadata should describe the model-facing contract: + +```md + +``` + +The renderer should combine workflow metadata, prompt metadata, and runtime metadata into generated per-action docs. Until then, this page is the canonical overview for agent actions. + +## Rendering expectations + +A future docs generator should: + +- scan `.github/workflows/agent-*.yml` for `kind: agent-action` +- scan `.github/prompts/*.md` for `kind: prompt` +- validate that every documented route has a workflow, prompt or skill source, session policy, and post-processing description +- render an overview table and optional per-action pages +- keep generated files separate from hand-written architecture pages + +The generator should not infer user-facing behavior only from raw workflow YAML. Workflow YAML should remain operational source code; `agent-doc` metadata should provide stable documentation intent. diff --git a/.agent/docs/actions/internal-actions.md b/.agent/docs/actions/internal-actions.md new file mode 100644 index 0000000..31d4651 --- /dev/null +++ b/.agent/docs/actions/internal-actions.md @@ -0,0 +1,15 @@ +# Internal actions + +Internal actions are shared composite GitHub Actions under `.github/actions/`. They are implementation building blocks consumed by workflows, not commands users invoke directly. + +| Action | Purpose | Key inputs | Key outputs or side effects | +|---|---|---|---| +| `.github/actions/setup-agent-runtime` | Bootstraps the runtime before an agent run | `node_version`, `install_codex`, `codex_version`, `install_claude`, `claude_version` | installs or verifies Node, runs `npm ci`, builds `.agent/dist`, adds tool bins to `PATH`, optionally installs Codex or Claude | +| `.github/actions/resolve-github-auth` | Resolves the GitHub token used by workflow steps and agent runs | `app_id`, `app_private_key`, `pat`, `fallback_token` | outputs `token` and `auth_mode`; selects GitHub App, hosted OIDC broker, PAT, or workflow-token auth | +| `.github/actions/resolve-agent-provider` | Resolves the provider for single-agent runs and review synthesis before runtime setup | `route`, `route_provider`, `default_provider`, `openai_api_key`, `claude_oauth_token`, `required` | outputs `provider`, `reason`, `install_codex`, and `install_claude`; selects explicit inline overrides or `AGENT_DEFAULT_PROVIDER` even without matching secrets, otherwise auto-detects from configured provider secrets | +| `.github/actions/check-agent-action-expiration` | Shared expiration guard for generated scheduled agent workflows | `expires_at` | outputs `expired`, `expires_at`, and `today`; validates a UTC `YYYY-MM-DD` expiration and skips generated workflows after that date without relying on GNU-only `date -d` parsing | +| `.github/actions/run-skill-setup` | Checks a repository skill and runs its optional `setup.sh` hook | `skill`, `skill_root`, `trusted_ref`, `run_setup` | outputs `exists`, `skill_path`, `setup_exists`, `setup_ran`, and `setup_path`; refuses setup from untrusted PR checkout refs | +| `.github/actions/run-agent-task` | Runs a prompt or skill through the runtime and `acpx` | `prompt`, `skill`, `agent`, `route`, `lane`, `target_*`, `source_kind`, `request_text`, `session_policy`, `session_bundle_mode`, `memory_policy`, `memory_mode_override`, `memory_ref`, `rubrics_policy`, `rubrics_mode_override`, `rubrics_ref`, `rubrics_limit` | renders the prompt, runs `.agent/dist/run.js`, captures response/session files, restores and uploads session bundles when enabled, resolves memory/rubrics modes, optionally mounts `agent/memory` and `agent/rubrics`, and commits permitted memory or validated rubric edits | +| `.github/actions/download-agent-memory` | Best-effort shallow clone of the repo-local `agent/memory` branch into `$RUNNER_TEMP/agent-memory` so the agent can read and write memory without staging it on the feature branch | `github_token`, `ref`, `path`, `continue_on_missing` | outputs `memory_available`, `memory_dir`, `memory_ref` | + +The memory-related inputs and CLIs (`memory/search.js`, `memory/update.js`, `memory/sync-github-artifacts.js`, `memory/read-sync-state.js`, `memory/write-sync-state.js`, `memory/resolve-policy.js`) are documented together in [Repository memory](../architecture/memory.md). Rubrics inputs and CLIs are documented in [User/team rubrics](../architecture/rubrics.md). diff --git a/.agent/docs/architecture/memory.md b/.agent/docs/architecture/memory.md new file mode 100644 index 0000000..33d0110 --- /dev/null +++ b/.agent/docs/architecture/memory.md @@ -0,0 +1,218 @@ +# Repository memory + +The agent composes long-lived memory across runs on a dedicated `agent/memory` branch. Memory is **agentic**: the main agent (on `answer`, `implement`, `fix-pr`, `review`, `skill`) reads and writes memory directly during normal tasks, using a pair of CLIs. Dedicated scheduled workflows curate memory outside user-driven work. + +Memory is separate from [user/team rubrics](./rubrics.md). Memory captures agent/project continuity and lessons the agent uses to improve its own work; rubrics capture normative user preferences used to steer implementation and score reviews. + +## Branch layout + +| Path | Purpose | +|---|---| +| `PROJECT.md` | Slow-changing project context: goals, constraints, open questions | +| `MEMORY.md` | Durable learned conventions and lessons the agent should carry forward | +| `daily/YYYY-MM-DD.md` | Append-only daily bullets composed by the agent | +| `github///{issue,pull,discussion}-.json` | Deterministic mirror of repo history, written by `agent-memory-sync.yml` | + +These are the seeded anchor files, not an exhaustive schema; the memory tree may also contain additional agent-created notes when that helps organize durable context. + +Markdown where humans curate (PROJECT / MEMORY / daily); raw `gh --json` output where the mirror just dumps. The `github/` layout is repo-namespaced so copied memory branches can retain old repo history while new syncs write into the current repo's namespace. Each namespace uses a `-.json` filename so issue #42, PR #42, and discussion #42 never collide — GitHub shares the issue/PR counter, and discussions use their own. + +Notes can cite mirrored artifacts with backlink-style paths, for example `[[github/self-evolving/repo/issue-238.json]]`. + +Previous adopters with flat artifacts such as `github/issue-*.json`, `github/pull-*.json`, or `github/discussion-*.json` should manually move active artifacts under the matching `github///` namespace or delete stale copied artifacts. Sepo does not automatically mutate the legacy flat layout, and `memory/search.js` searches recursively, so leftover flat artifacts can still appear in search results and mix old and new repository context. + +The mirror preserves exactly what `gh` returns so the agent can query with `jq`: + +```bash +jq '.comments[].body' "$MEMORY_DIR/github/self-evolving/repo/issue-209.json" +jq 'select(.state == "MERGED") | .title' "$MEMORY_DIR/github/self-evolving/repo/pull-"*.json +``` + +`memory/search.js` already handles `.json` files, so tokenized text search still works on field values. + +Sync cursors for the mirror live in a separate ref, `refs/agent-memory-state/sync`, so cursor updates don't pollute the memory branch's commit history. This follows the same ref-backed state pattern used by session continuity thread state: operational cursor state stays off the human-facing memory branch. The state records `repo_slug`; if a copied branch carries state for another repository, the read/write CLIs ignore it and start a fresh cursor for the current repo. + +## Memory CLIs + +Main routes mount the memory branch at `$MEMORY_DIR` and expose two CLIs to the agent: + +| CLI | Purpose | +|---|---| +| `node .agent/dist/cli/memory/search.js --dir "$MEMORY_DIR" ""` | Tokenized filesystem search with snippets | +| `node .agent/dist/cli/memory/update.js --dir "$MEMORY_DIR" [...]` | Validated helper for bullet-level edits to `MEMORY.md` / `PROJECT.md` / `daily/*.md` | + +The agent can read and edit files under `$MEMORY_DIR` with normal tools. For standard bullet-oriented changes, `memory/update.js` is the preferred helper because it keeps section placement, formatting, and dedup consistent. The outer workflow commits any resulting diff to `agent/memory` using the workflow's token — the agent never needs push access. + +### How `memory/update.js` changes files + +```mermaid +flowchart TD + A[Agent decides memory needs an edit] --> B{Which subcommand?} + + B -->|add| C[Validated section-scoped bullet edit] + B -->|replace| C + B -->|remove| C + B -->|daily-append| D[Append daily activity bullet] + + C --> E{--file target} + E -->|MEMORY.md| F[$MEMORY_DIR/MEMORY.md] + E -->|PROJECT.md| G[$MEMORY_DIR/PROJECT.md] + + D --> H[$MEMORY_DIR/daily/YYYY-MM-DD.md] + H --> I{Daily log exists?} + I -->|no| J[Create file with Activity section] + I -->|yes| K[Reuse existing file] + J --> L[Append deduped bullet] + K --> L + + F --> M[Workflow later commits and pushes agent/memory diff] + G --> M + L --> M +``` + +File impact is intentionally narrow: + +- `add`, `replace`, and `remove` change exactly one file: `$MEMORY_DIR/MEMORY.md` or `$MEMORY_DIR/PROJECT.md`. +- `daily-append` changes exactly one dated log: `$MEMORY_DIR/daily/YYYY-MM-DD.md`, creating it first when missing. +- `memory/update.js` never mutates `github///*.json`; those files only change during the deterministic mirror sync. +- Agents may also edit repo-local memory files directly when they need a shape the CLI does not cover; the CLI is the safe default for simple bullet updates. + +### `update.js` outcomes + +The CLI exits 0 on success (stdout) and 2 on caller-fixable errors (stderr). `replace` has two success shapes worth calling out: + +| Result | Meaning | Action | +|---|---|---| +| `replaced bullet in ` | `--match` resolved to a single bullet; `--with` is novel | source line rewritten | +| `collapsed duplicate bullet in ` (`deduped`) | `--match` resolved, but `--with` already exists as a distinct bullet | source line removed, existing target kept (net: one fewer bullet, no duplicate) | +| `no change (duplicate): ` (`noop`) | `--match` resolved to a bullet that already equals `--with` | no write | +| `no bullet matched: in ` | `--match` found nothing | exit 2 | +| `multiple bullets matched: in ` | `--match` resolved to ≥2 *distinct* bullets | exit 2, stderr lists candidates; the agent should refine `--match` | + +`remove` uses the same matching rules: single-match removes, multi-match refuses with `ambiguous_match`, zero-match refuses with `missing_match`. + +Non-LLM support CLIs used by the scheduled workflows: + +| CLI | Purpose | +|---|---| +| `memory/bootstrap-branch.js` | Local helper that creates or updates a local `agent/memory` branch and seeds the memory tree | +| `memory/sync-github-artifacts.js` | Mirrors issues, PRs, and discussions into `github///*.json` | +| `memory/read-sync-state.js` / `memory/write-sync-state.js` | Read and write cursors stored at `refs/agent-memory-state/sync` | +| `memory/resolve-policy.js` | Internal to `run-agent-task`; resolves the effective memory mode per run | + +## Workflows + +Four workflows complement the main execution routes: + +| Workflow | Trigger | Purpose | LLM | +|---|---|---|---| +| `agent-memory-bootstrap.yml` (`Agent / Memory / Initialization`) | `workflow_dispatch` | Initialize `agent/memory` on first run from GitHub Actions, then run the initial sync and scan inline | Auto | +| `agent-memory-sync.yml` (`Agent / Memory / Sync GitHub Artifacts`) | `schedule` (every 6h), `workflow_dispatch` | Deterministic mirror of recent GitHub artifacts | No | +| `agent-memory-pr-closed.yml` (`Agent / Memory / Record PR Closure`) | `pull_request_target.closed`, `workflow_dispatch` | Agent curates memory when a PR closes. Skips unmerged fork PRs (fork safety). | Yes | +| `agent-memory-scan.yml` (`Agent / Memory / Curate Recent Activity`) | `schedule` (every 6h), `workflow_dispatch` | Agent reviews recent activity and curates durable memory | Yes | + +`agent-memory-bootstrap.yml` is the explicit setup path for existing repositories: it fails if the memory branch already exists, seeds the anchor files into a fresh `agent/memory` branch, pushes that first commit directly from Actions, then runs the initial sync and scan steps inline to populate the branch. + +Both agent-driven scaffolds invoke the same `run-agent-task` action as the main routes. They can use the same memory CLIs and the same normal file-editing tools against the mounted memory checkout. + +`agent-memory-scan.yml` is repo-scoped rather than thread-scoped, so it runs with `target_kind: repository`, `target_number: 0`, and the repository URL as its target identity. Scheduled scan runs first check whether the sync activity cursor has advanced since the last successful scan; manual `workflow_dispatch` runs bypass that schedule gate. + +The dedicated memory workflows can still bootstrap the memory tree when the branch does not exist yet, so a fresh repo can initialize `agent/memory` on its first sync/curation run even without the explicit bootstrap workflow. Normal routes still degrade gracefully when memory is absent. + +## Scheduled workflow policy: `AGENT_SCHEDULE_POLICY` + +`AGENT_SCHEDULE_POLICY` is an optional repository variable that controls scheduled workflow runs. It applies only to `schedule` events; manual `workflow_dispatch` runs remain available for debugging and recovery. + +**Default**: scheduled workflows use `skip_no_updates`, with `agent-daily-summary.yml` set to `disabled` and `agent-memory-sync.yml` set to `always_run`. + +**Modes**: + +- `always_run` — run every cron tick +- `skip_no_updates` — run only when the workflow's activity detector finds relevant work +- `disabled` — skip cron-triggered work while preserving manual dispatch + +**Policy shape**: + +```json +{ + "default_mode": "skip_no_updates", + "workflow_overrides": { + "agent-daily-summary.yml": "disabled", + "agent-memory-sync.yml": "always_run" + } +} +``` + +Workflow overrides are keyed by workflow filename. Today, `agent-memory-scan.yml` compares `refs/agent-memory-state/sync.last_activity_at` with `refs/agent-memory-state/scan.last_scan_at` and records the scan cursor only after a successful scan. After the sync state has an initial baseline, the sync activity cursor advances only when issue, pull request, or discussion activity is mirrored, so no-op sync runs do not force a scan. `agent-daily-summary.yml` is disabled for scheduled runs by default; when enabled, it currently counts issue, pull request, and discussion signals in its lookback window and skips when that count is zero. It also checks discussion posting availability before signal collection so repositories without discussions, or without the configured discussion category, skip summary generation early. Commit-only activity is not counted yet. `agent-memory-sync.yml` has no external detector, so it should usually be set to `always_run`; if the policy resolves it to `disabled`, the cron run stops before sync work begins. + +## Access policy: `AGENT_MEMORY_POLICY` + +`AGENT_MEMORY_POLICY` is an optional repository variable that controls which routes can read or write memory. Mirrors the shape of `AGENT_ACCESS_POLICY`. + +**Default**: every route gets `enabled` (full read+write). + +**Modes**: + +- `enabled` — mount memory, commit+push edits after the run +- `read-only` — mount memory, skip the commit step +- `disabled` — skip memory entirely + +**Policy shape**: + +```json +{ + "default_mode": "enabled", + "route_overrides": { + "review": "read-only", + "dispatch": "disabled" + } +} +``` + +Either key is optional. Examples: + +- `{"route_overrides": {"review": "read-only"}}` — default-enabled, but review runs don't write +- `{"default_mode": "read-only"}` — nothing writes memory automatically; the dedicated scaffolds still do +- `{"default_mode": "disabled"}` — main routes never touch memory; only the scheduled scaffolds curate + +The dedicated memory workflows (`agent-memory-pr-closed.yml`, `agent-memory-scan.yml`) bypass the memory policy by passing `memory_mode_override: 'enabled'` on their `run-agent-task` call, so memory access stays available for curation. Scheduled runs are still governed by `AGENT_SCHEDULE_POLICY`; to stop scheduled scan work while preserving manual dispatch, set a workflow override to `disabled`. + +## Execution and security + +### Fork safety on PR close + +`agent-memory-pr-closed.yml` triggers on `pull_request_target: [closed]`, which runs in the base-repo context with write-scoped tokens. To keep attacker-controlled fork PR content from reaching the LLM with a write token, the job-level `if` restricts execution to: + +- same-repo PRs, or +- merged fork PRs (content was reviewed and merged), or +- manual `workflow_dispatch`. + +Closed-without-merge fork PRs are skipped. + +Merged fork PRs remain a deliberate trust trade-off. The PR title/body/comments/reviews are still user-controlled metadata and some of that metadata can change after merge, but v3 accepts that post-merge input for memory curation rather than dropping fork PRs entirely. If that boundary is too loose for a repository, tighten the workflow to skip fork PRs or reduce the prompt to trusted post-merge signals only. + +### Per-job permissions on review + +Review is the least-trusted route because it ingests arbitrary PR diffs. `agent-review.yml` keeps the matrix reviewer jobs at `contents: read` and explicitly forces `memory_mode_override: 'read-only'` on them — reviewers can consult memory but can't write. + +Only the `synthesize` job gets `contents: write` and uses the default policy-resolved mode. This also avoids the parallel-push race (two reviewer jobs contending for a fast-forward on the same ref) that would otherwise arise from running both `claude-review` and `codex-review` concurrently. + +### Memory commit gating + +The post-run commit in `run-agent-task` is gated on three conditions, all of which must hold: + +1. `steps.run.outputs.exit_code == '0'` — the agent ran cleanly +2. `steps.memory_mode.outputs.write_enabled == 'true'` — policy allows writes +3. `steps.memory.outputs.memory_available == 'true' && memory_dir != ''` — memory was successfully mounted + +Failed or interrupted runs never push partial edits. + +## Flags on `run-agent-task` + +| Input | Purpose | +|---|---| +| `memory_policy` | Policy JSON (overrides `vars.AGENT_MEMORY_POLICY` when passed) | +| `memory_mode_override` | Force a specific mode, bypassing policy. `enabled` is used by memory-scaffold workflows and also bootstraps the memory tree on first use. | +| `memory_ref` | Branch to clone (usually passed as `vars.AGENT_MEMORY_REF` or `agent/memory`) | + +The action exposes `memory_mode`, `memory_available`, `memory_dir`, and `memory_committed` as outputs for callers that need to branch on the mode. diff --git a/.agent/docs/architecture/overall-design.md b/.agent/docs/architecture/overall-design.md new file mode 100644 index 0000000..c411e43 --- /dev/null +++ b/.agent/docs/architecture/overall-design.md @@ -0,0 +1,72 @@ +# Overall design + +The `.agent` backend exposes a small set of GitHub-native agent workflows. Agent execution goes through the direct `acpx exec/prompt` path, with session continuity handled by `SessionPolicy` plus git-ref thread state. + +## Triggering modes + +- **User initiated** + - mentions in issues, PRs, discussions, and comments + - labels such as `agent/answer` or `agent/s/` +- **Workflow initiated** + - downstream reusable workflows dispatched by the router after route resolution or approval +- **Scheduled or autonomous actions** + - TODO + +Approval comments such as `@sepo-agent /approve ` are part of the implementation lifecycle rather than a separate top-level trigger mode. See [The life cycle of an agent request](request-lifecycle.md) for that path. + +## Portal flow + +The first half of the portal flow decides whether the trigger should run at all and, if so, which route it should take. + +```mermaid +flowchart LR + trigger["@sepo-agent mention or agent/* label"] + gate{Bot or\nunauthorized?} + mention{Live mention\nafter stripping\ncode/quotes?} + react["React with 👀"] + explicit{Explicit slash\nroute command?} + triage["Dispatch triage\n(approve-all, medium effort)"] + route{Route?} + + trigger --> gate + gate -- yes --> skip(["Skip"]) + gate -- no --> mention + mention -- no --> skip + mention -- yes --> react --> explicit + explicit -- yes --> route + explicit -- no --> triage --> route +``` +Once the route is resolved, the backend either answers inline, asks for approval, or dispatches a route-specific workflow. + +```mermaid +flowchart LR + route{Route?} + + answer_run["Answer agent\n(approve-all, high effort)"] + post_answer["Post reply on\noriginal surface"] + + is_issue{Source is\nan issue?} + post_approval_issue["Post approval request\non issue"] + post_proposal["Post proposed issue\non original surface"] + approve["User replies:\n@agent approve"] + create_issue["Create issue from\napproved proposal"] + dispatch_impl["Dispatch\nagent-implement.yml"] + dispatch_fix["Dispatch\nagent-fix-pr.yml"] + dispatch_review["Dispatch\nagent-review.yml"] + react_thumbs["React with 👍"] + + route -- "answer / unsupported" --> answer_run --> post_answer + route -- "implement" --> is_issue + is_issue -- yes --> post_approval_issue --> approve --> dispatch_impl + is_issue -- no --> post_proposal --> approve --> create_issue --> dispatch_impl + route -- "fix-pr (PR only, not on edit)" --> dispatch_fix --> react_thumbs + route -- "review (PR only, not on edit)" --> dispatch_review --> react_thumbs +``` + +## Structure + +### TypeScript runtime (`.agent/src/`) + +All shared modules live flat in `.agent/src/`. CLI entrypoints live in `.agent/src/cli/`. Tests live in `.agent/src/__tests__/`. Package metadata lives in `.agent/package.json` and `.agent/tsconfig.json`. + +Long-lived [agent-owned memory](memory.md) and [user-owned rubrics](rubrics.md) are intentionally separate state surfaces: `agent/memory` captures agent/project continuity, while `agent/rubrics` captures normative user/team preferences used for implementation steering and review scoring. diff --git a/.agent/docs/architecture/request-lifecycle.md b/.agent/docs/architecture/request-lifecycle.md new file mode 100644 index 0000000..707297a --- /dev/null +++ b/.agent/docs/architecture/request-lifecycle.md @@ -0,0 +1,52 @@ +# The life cycle of an agent request + +## Entry and routing + +Every trigger converges on the portal workflow `agent-router.yml`. It extracts context, validates mentions, records the caller association, optionally runs dispatch triage, applies route authorization, and routes the request to a specialized workflow or inline answer path. + +## Approval model + +- Inline answers are posted immediately. +- Review and `fix-pr` requests on pull requests are dispatched immediately. +- Explicit `/orchestrate` (or `agent/orchestrate`) requests dispatch the orchestrator workflow, which chooses one follow-up action from current target state. +- Edited PR events are blocked from re-triggering review and `fix-pr` routes. +- Mention and label requests that fail route authorization are posted back as inline `unsupported` replies instead of being dropped silently; that path still runs `Setup agent runtime` before `post-response.js` so posting dependencies are available. +- Triaged implementation requests (i.e., when the dispatch agent predicts `implement` from a free-form mention) require an approval comment: + - `@sepo-agent /approve req-...` +- For triaged implementation requests from non-issue surfaces, the router drafts an issue title and body, posts the proposal on the original surface, and creates the issue after approval. +- Explicit implementation requests (`@sepo-agent /implement ...` or the `agent/implement` label) skip the approval comment. The router creates a tracking issue if the surface isn't already an issue and dispatches `agent-implement.yml` directly, since the explicit mention is itself the approval. For pull request and discussion surfaces, the router asks a metadata-only agent prompt to synthesize the tracking issue title and body from the request and target context; for PR requests that explicitly ask for stacked or follow-up work, that metadata can also provide `base_pr` so the implementation PR stacks on the source PR head. If that metadata is unavailable or invalid, it falls back to the generic implementation issue metadata. Access control (`AGENT_ACCESS_POLICY`) still applies to the `implement` route. The explicit path also passes a session-fork hint from the original target's `answer/default` thread, so implementation can continue from a prior answer session when that bundle exists. + +PR fix requests never create a tracking issue or a new pull request. The runner updates the existing PR branch after reading PR metadata and review comments. Dirty worktree changes are committed and pushed back to the PR branch; clean history-only updates, such as a successful rebase, run verification against the original PR head and then push the updated `HEAD` back to the PR branch with a lease against that original head. If persistence fails after a successful agent run, the final status comment reports the run as failed. Automatic pushing is limited to open same-repository pull requests, and route access follows the configured trigger access policy. + +## Branch naming + +Agent workflows that create branches use: + +```text +agent/--/- +``` + +For example: + +```text +agent/implement-issue-42/codex-23948660610 +``` + +The run ID makes each attempt unique to avoid push conflicts on retries. The branch name is set once at the job `env:` level and reused by all steps. Routes that work on existing branches, such as `fix-pr`, do not create new branches. + +## Permission model + +Current route-level `acpx` permission modes: + +| Route | acpx mode | Rationale | +|---|---|---| +| `dispatch` | `approve-all` | classification may gather repo and issue context | +| `answer` | `approve-all` | may gather context before replying | +| `orchestrator` | `approve-all` | planner may gather target and repository context before choosing the next route | +| `agent-self-approve` | `approve-reads` | final approval judgment may inspect PR/repo context, but deterministic resolver code owns approval submission | +| `agent-self-merge` | none | deterministic workflow code owns current-head approval validation and merge submission | +| `implement` | `approve-all` | needs full file system access | +| `fix-pr` | `approve-all` | needs full file system access | +| `review` | `approve-all` | reviewers and synthesis may gather PR and repo context | + +Dedicated memory and rubric maintenance workflows use the same runtime but are documented with their storage systems rather than the user-request lifecycle. Workflow-level GitHub token scopes are set by each workflow or job and remain separate from route-level `acpx` modes. The self-approval workflow keeps the inspection agent on the read-scoped `github.token`; deterministic resolver code uses the resolved Sepo auth token for approval submission. Self-merge has no model step; its deterministic resolver uses the resolved Sepo auth token only after current-head self-approval, checks, mergeability, and requested-change guards pass. diff --git a/.agent/docs/architecture/rubrics.md b/.agent/docs/architecture/rubrics.md new file mode 100644 index 0000000..f826ed0 --- /dev/null +++ b/.agent/docs/architecture/rubrics.md @@ -0,0 +1,128 @@ +# User/team rubrics + +Rubrics are a separate durable system from repository memory. + +- `agent/memory` stores agent/project continuity: what the agent learns about the repository, prior work, and its own operating context. +- `agent/rubrics` stores user/team preferences: what users want future agent work to optimize for and what review should evaluate. + +Rubrics are therefore normative, not merely contextual. Normal implementation and review runs read them, but only dedicated rubrics workflows should write them. + +## Branch layout + +Rubrics live on a dedicated branch, `agent/rubrics` by default. The branch is mounted into runs as `$RUBRICS_DIR`. + +Seeded layout: + +| Path | Purpose | +|---|---| +| `README.md` | Describes the rubrics branch and its distinction from memory | +| `rubrics/coding/*.yaml` | Coding style / coding workflow rubrics | +| `rubrics/communication/*.yaml` | Communication rubrics | +| `rubrics/workflow/*.yaml` | Development workflow rubrics | + +Each rubric is one YAML file. Subdirectories are organizational; the schema fields remain the source of truth. + +## Schema + +```yaml +schema_version: 1 +id: add-regression-tests +title: Add regression tests for bug fixes +description: >- + When fixing a bug, include a regression test that fails before the fix + and passes after it. +type: generic # generic | specific +domain: coding_workflow # coding_style | coding_workflow | communication | review_quality +applies_to: + - implement # implement | fix-pr | review | agent-self-approve | agent-self-merge | answer | skill | rubrics-review | rubrics-initialization | rubrics-update +severity: should # must | should | consider +weight: 3 # 1-10 +status: active # active | draft | retired +examples: + - source: https://github.com/self-evolving/repo/pull/96 + note: Reviewer asked for stronger validation and tests around workflow behavior. +``` + +Required fields are `id`, `title`, `description`, and `applies_to`. Missing optional fields default as follows: + +| Field | Default | +|---|---| +| `schema_version` | `1` | +| `type` | `generic` | +| `domain` | `coding_workflow` | +| `severity` | `should` | +| `weight` | `1` | +| `status` | `active` | +| `examples` | `[]` | + +The legacy `category: coding` field is accepted as a fallback for `domain` during migration, but new rubrics should use `domain`. + +## Runtime use + +`run-agent-task` resolves rubric access with `AGENT_RUBRICS_POLICY`, downloads the rubrics branch when enabled, selects route-applicable rubrics, and prepends `.github/prompts/_rubrics.md` to the route prompt. + +Dispatch triage is always rubric-disabled. Rubrics should steer concrete work and review, not route selection. + +Selection is intentionally simple and acts as prompt-time retrieval guidance: + +1. Load `rubrics/**/*.yaml`. +2. Validate schema and unique IDs. +3. Keep active rubrics whose `applies_to` includes the current route. `implement` rubrics also apply to `fix-pr` as baseline implementation guidance. +4. For answer runs, keep only communication-domain rubrics so answer behavior is steered by communication preferences. +5. Rank by severity, weight, and token matches against request text. +6. Inject the top N rubrics into the prompt through `${RUBRICS_CONTEXT}` as a starting shortlist. + +The prompt also tells agents that `$RUBRICS_DIR` is browseable. Agents can inspect the checkout for additional active user/team rubrics when the selected shortlist is incomplete for implementation, PR fixes, reviews, or answers. + +Read-only selection is best-effort: invalid rubric files are emitted as workflow warnings and valid rubrics still steer the agent. The write path remains strict; dedicated rubrics workflows validate the full checkout before committing. + +## Workflows + +| Workflow | Trigger | Purpose | Writes `agent/rubrics`? | +|---|---|---|---| +| `agent-rubrics-initialization.yml` (`Agent / Rubrics / Initialization`) | `workflow_dispatch` | Creates `agent/rubrics`, seeds the branch layout, and asks an agent to populate initial rubrics from supplied context or repository history | Yes | +| `agent-rubrics-review.yml` (`Agent / Rubrics / Review`) | `workflow_dispatch`, `workflow_call` | Scores a PR against selected active rubrics and uploads or posts a review artifact | No | +| `agent-rubrics-update.yml` (`Agent / Rubrics / Update`) | merged `pull_request_target.closed` with review interaction, `workflow_dispatch` | Distills durable user/team preferences from merged PR conversations | Yes | + +`agent-review.yml` calls `Agent / Rubrics / Review` as an independent review lane that posts its own PR comment. Core review synthesis does not depend on rubrics review, so rubric scoring failures do not block the normal review comment. + +`Agent / Rubrics / Initialization` is the recommended first-run setup path. It rejects existing rubrics branches, bootstraps the branch skeleton, then runs an initialization prompt. Operators can provide arbitrary context, such as desired team preferences or links to important PRs/issues. When context is omitted, the agent inspects recent merged PRs and trusted contributor feedback to seed only durable rubrics. Initialization fails if the workflow cannot commit and push the new rubrics branch. + +`Agent / Rubrics / Update` posts a short PR summary after each completed learning run. The summary says whether `agent/rubrics` was committed and includes the agent's explanation, including `no rubric changes` decisions, so skipped learning is visible without opening Actions logs. + +Rubric learning remains conservative about trust. Owner/admin/maintain comments are primary signals, and `OWNER`, `MEMBER`, and `COLLABORATOR` author associations are trusted contributor signals for clear durable preferences. On automatic merged-PR update runs, the `requested_by` field is the close/merge actor; if that same actor authored an explicit request to add or update rubrics, the prompt treats that source as trusted even when best-effort GitHub App collaborator lookups are incomplete. That exception does not trust other PR participants. + +## Access policy: `AGENT_RUBRICS_POLICY` + +Rubrics policy mirrors memory policy but defaults to `read-only`, because rubrics are user/team preferences and should not be casually mutated by normal task runs. + +```json +{ + "default_mode": "read-only", + "route_overrides": { + "rubrics-update": "enabled", + "answer": "disabled" + } +} +``` + +Modes: + +- `enabled` — mount rubrics and commit validated edits after a successful run +- `read-only` — mount rubrics and inject selected rubrics, but skip commits +- `disabled` — skip rubrics entirely + +Dedicated rubric-initialization and rubric-update runs pass `rubrics_mode_override: enabled`, so they can write the branch even when the repository default is read-only. Only rubric initialization bootstraps a missing branch; rubric update expects `agent/rubrics` to already exist. + +Normal implementation, fix, review, and rubric-review callers do not pass a rubric mode override; they honor `AGENT_RUBRICS_POLICY` and default to read-only when no policy is configured. + +## CLIs + +| CLI | Purpose | +|---|---| +| `rubrics/init.js` | Seed a local rubrics checkout | +| `rubrics/validate.js` | Validate rubric YAML files and unique IDs | +| `rubrics/select.js` | Select and render applicable rubrics for a route | +| `rubrics/resolve-policy.js` | Resolve effective route mode | + +Validation runs before committing rubric edits. Invalid YAML or duplicate IDs fail the write path rather than publishing broken rubrics. diff --git a/.agent/docs/architecture/supported-workflows.md b/.agent/docs/architecture/supported-workflows.md new file mode 100644 index 0000000..4495dc5 --- /dev/null +++ b/.agent/docs/architecture/supported-workflows.md @@ -0,0 +1,312 @@ +# Supported workflows + +## Workflow reference + +### Core workflows + +| Workflow | Trigger | Purpose | Model | +|---|---|---|---| +| `agent-label.yml` | `issues.labeled`, `pull_request_target.labeled` | Thin entry point for label-based activation into `agent-router.yml` | None | +| `agent-entrypoint.yml` | `@sepo-agent` in issues, PRs, discussions, comments, reviews | Thin entry point that wires triggers, runner labels, and secrets into `agent-router.yml` | None | +| `agent-router.yml` | `workflow_call` | Full portal for context extraction, auth gating, mention detection, dispatch triage, routing, approval requests, and response posting | Configurable | +| `agent-approve.yml` | approval comments | Resolves pending approvals, creates issues when needed, dispatches implementation | None | +| `agent-orchestrator.yml` | `workflow_dispatch` | Explicit orchestration route that decides whether to dispatch the next action | None in `heuristics` mode; resolved-provider planner in `agent` mode | +| `agent-self-approve.yml` | `workflow_dispatch` | Opt-in pull request self-approval gate after trusted current-head review synthesis | Auto | +| `agent-self-merge.yml` | `workflow_dispatch` | Opt-in deterministic merge gate after current-head Sepo self-approval | None | +| `agent-implement.yml` | `workflow_dispatch` | Implementation flow: branch, commit, draft PR; supports `base_branch` or `base_pr` for stacked PRs | Auto | +| `agent-fix-pr.yml` | `workflow_dispatch`, `workflow_call` | PR fix flow: update existing PR branch, verify, push | Auto | +| `agent-review.yml` | `workflow_dispatch`, `workflow_call` | Parallel Claude and Codex review with resolved-provider synthesis, captured reviewed-head provenance, plus a separate rubric review comment | Claude + Codex reviewers; configurable synthesis | +| `agent-branch-cleanup.yml` | `pull_request_target.closed` | Event-driven cleanup of merged agent-created branches after retargeting open stacked PRs. Excludes the shared `agent/memory` and `agent/rubrics` branches. | None | +| `agent-close-stale-issues.yml` | `schedule` (daily), `workflow_dispatch` | Closes open `agent` issues that have had no activity for 30 days by default | None | +| `agent-daily-summary.yml` | `schedule` (daily, disabled by default), `workflow_dispatch` | Generates a concise repository activity summary and posts it as a Discussion | Auto | +| `agent-project-manager.yml` | `schedule` (every 6h), `workflow_dispatch` | Opt-in agent-driven triage for open issues and PRs, with dry-run summaries and optional priority/effort label updates | Auto | +| `agent-update.yml` | `schedule` (1st and 15th), `workflow_dispatch` | Checks for Sepo agent infrastructure updates and opens a PR only when updates are available | Auto | +| `agent-onboarding.yml` | `workflow_dispatch` | First-run setup check that creates built-in trigger labels and opens or updates a setup issue | None | +| `test-scripts.yml` | `pull_request`, `workflow_dispatch` | CI for helper tests, YAML parsing, and shell syntax | None | + +`agent-orchestrator.yml` is started explicitly through `/orchestrate` or +`agent/orchestrate`. Dispatch triage can also select `orchestrate` for issue and +pull request requests that ask for orchestration, follow-up automation, or +bounded multi-step agent work. On start, it inspects the current target state and +dispatches one built-in action (`implement`, `review`, `fix-pr`, +`agent-self-approve`, or `agent-self-merge`) when useful. +That dispatch includes explicit orchestration context; only those orchestrator +launched action runs hand back to `agent-orchestrator.yml` after post-processing. +Direct `/implement`, `/review`, and `/fix-pr` runs remain one-shot. Pull request +orchestrate starts remain deterministic in `heuristics` mode. In `agent` mode, +issue-level and pull-request-level orchestrate starts may use the planner. For +small self-contained issue work, the planner can return a normal handoff to +`implement` on the current issue. For PR work, the planner can choose +review-first, fix-the-PR, answer-only, or stop behavior; runtime policy validates +that PR starts dispatch only `review` or `fix-pr` workflows. For +meta-orchestration, the planner can return an internal `delegate_issue` command +instead of adding a new public route. That command creates or reuses a child +issue with parent/stage metadata, dispatches the child issue through the normal +`/orchestrate` flow in heuristic mode, and keeps the parent/child relationship +in GitHub issue state rather than session identity. +When `delegate_issue` names an existing user-authored issue, the orchestrator +adopts it by writing the trusted child marker in an agent-authored issue comment +and recording the parent/child link on the parent issue. The dispatcher also +best-effort adds the child as a GitHub sub-issue of the parent when the +repository supports that REST API; trusted markers remain the fallback relation +if the API is unavailable. + +Planner-based selection is also used for action-originated handoff runs. The planner can include a +`handoff_context` string for the next action; `fix-pr` receives it as explicit +initial steering when the planner dispatches a PR-fix pass. The planner mounts +memory and rubrics read-only so automated control-flow planning can use steering +context without mutating those state branches. Orchestration stops when target +state indicates no safe next action, a route fails, a duplicate handoff marker +is found, the planner stops or blocks, or the max-round budget is exhausted. + +When a child issue reaches a terminal stop, the handoff dispatcher resolves the +trusted child metadata from the issue body or an agent-authored child issue +comment, or from the pull request body's closing issue reference when the +terminal target is a PR. It then posts or updates a visible progress comment on +the parent issue, dispatches the parent issue orchestrator again in agent mode, +and only then marks the trusted child marker as `done`, `blocked`, or `failed`. +Already-dispatched terminal reports are idempotent so reruns do not overwrite +completed child state. + +Because `/orchestrate` can delegate into implementation, review, fix, enabled +self-approval workflows, and enabled self-merge workflows, initial +user-launched orchestrate requests validate the requester against the delegated +route capability set up front. `agent-self-approve` is included in that check +only when `AGENT_ALLOW_SELF_APPROVE=true`; `agent-self-merge` is included only +when both `AGENT_ALLOW_SELF_APPROVE=true` and `AGENT_ALLOW_SELF_MERGE=true`. +Internal child and parent resume dispatches carry `requested_by` for audit and +display, but they do not thread route authorization inputs through every child +workflow. + +Implementation dispatches default to the repository default branch. Callers can +set `base_branch` to stack directly on another branch, or `base_pr` to stack on +an open same-repository PR head branch. The implementation workflow rejects +ambiguous input when both are set. + +For explicit `/implement` requests from pull requests, the router's +metadata-only prompt may emit `base_pr` when the current user request asks for a +stacked or follow-up PR. The portal validates that value as a positive integer +and passes it through to `agent-implement.yml`; the implementation workflow then +verifies the PR is open and same-repository before using its head branch. + +When a new review synthesis, rubrics review, `fix-pr` status comment, or +orchestrator handoff marker is posted, the workflows minimize prior visible +matching comments and reviews from the same authenticated agent account as +outdated. Generated review summaries and `fix-pr` status comments carry hidden +HTML markers for robust matching, with heading/text fallbacks for older +comments. Rubrics reviews match the `## Rubrics Review` heading, and +orchestrator handoffs match their hidden handoff marker. This keeps the latest +generated status prominent while leaving older generated comments expandable. +Set `AGENT_COLLAPSE_OLD_REVIEWS=false` to skip this cleanup and leave prior +generated comments visible. + +Review runs also attempt to capture the pull request head before reviewer lanes +start. The synthesis comment includes a hidden reviewed-head marker only if the +pull request still points at that same head before posting. If capture, +comparison, or prepare metadata setup cannot read PR metadata, synthesis still +posts without the hidden marker. + +Review synthesis can also make prompt-managed inline review comment updates: +it may post a new inline comment, reply to an existing same-agent inline +comment, or clean up older same-agent inline feedback by synthesis-agent +judgment. Synthesis re-fetches PR inline comments and review threads before +cleanup. It resolves an older same-agent review thread only when the thread +belongs to the PR, is unresolved, `viewerCanResolve` is true, every thread +comment is from the same authenticated agent account, and the issue is +addressed or superseded. It marks an older same-agent inline comment as +outdated only when the comment is superseded and there is no appropriate +resolvable review-thread path. When authorship, PR ownership, supersession, or +resolution confidence is uncertain, synthesis does nothing. Reviewer lanes only +suggest these actions; they do not mutate GitHub. This inline behavior is +separate from the deterministic generated-comment cleanup controlled by +`AGENT_COLLAPSE_OLD_REVIEWS`. + +### Repository memory workflows + +| Workflow | Actions name | Trigger | Purpose | Model | +|---|---|---|---|---| +| `agent-memory-bootstrap.yml` | `Agent / Memory / Initialization` | `workflow_dispatch` | Seed the `agent/memory` branch on first run, then perform the initial sync and scan inline | Auto | +| `agent-memory-sync.yml` | `Agent / Memory / Sync GitHub Artifacts` | `schedule` (every 6h), `workflow_dispatch` | Deterministic mirror of issues, PRs, and discussions into the `agent/memory` branch | None | +| `agent-memory-pr-closed.yml` | `Agent / Memory / Record PR Closure` | `pull_request_target.closed`, `workflow_dispatch` | Agent-driven memory curation run triggered when a PR closes. Skips unmerged fork PRs. | Auto | +| `agent-memory-scan.yml` | `Agent / Memory / Curate Recent Activity` | `schedule` (every 6h), `workflow_dispatch` | Scheduled agent-driven memory curation across recent repository activity | Auto | + +The `agent-memory-*` workflows and the `agent/memory` branch they share are documented in [Repository memory](./memory.md), including the layout, the `AGENT_MEMORY_POLICY` configuration, and per-route permission rules. + +### User/team rubrics workflows + +| Workflow | Actions name | Trigger | Purpose | Model | +|---|---|---|---|---| +| `agent-rubrics-initialization.yml` | `Agent / Rubrics / Initialization` | `workflow_dispatch` | Creates `agent/rubrics`, seeds the layout, and optionally populates initial rubrics from supplied context or repository history | Auto | +| `agent-rubrics-review.yml` | `Agent / Rubrics / Review` | `workflow_dispatch`, `workflow_call` | Scores a PR against active rubrics selected from `agent/rubrics` | Auto | +| `agent-rubrics-update.yml` | `Agent / Rubrics / Update` | merged `pull_request_target.closed`, `workflow_dispatch` | Learns durable user/team preferences from PR interactions and updates `agent/rubrics` | Auto | + +Rubrics are documented in [User/team rubrics](./rubrics.md). They are separate from repository memory: memory is agent/project continuity, while rubrics are normative user/team preferences used to steer implementation and evaluate reviews. + +`agent-branch-cleanup.yml` and `agent-close-stale-issues.yml` are standalone +workflows. They listen directly to repository events or schedules and apply +their guardrails in place. Before deleting a merged agent branch, +`agent-branch-cleanup.yml` retargets open PRs based on that branch to the +merged PR's base branch; if a retarget fails, the branch is left in place. + +`agent-project-manager.yml` is disabled by default. Enable scheduled runs with +`AGENT_PROJECT_MANAGEMENT_ENABLED=true`, or run it manually with the `enabled` +input. It launches a prompt-driven, read-approved agent to inspect open issues +and pull requests, assess priority/effort with judgment rather than fixed +heuristics, and return a GitHub-flavored summary plus a structured managed-label +change plan. A deterministic post-agent CLI validates that plan and applies only +managed `priority/*` and `effort/*` add/remove operations when label application +is enabled and dry-run mode is disabled. Label application defaults enabled, but +dry-run mode defaults enabled too, so scheduled runs still report planned +changes without mutating labels until dry-run is disabled. The schedule runs +every 6 hours at minute 17 UTC. A +final workflow step writes the resulting summary to the Actions step summary. +Optional summary comments require `post_summary=true`; when enabled, that final +step finds today's `Daily Summary — YYYY-MM-DD` discussion in the configured +discussion category and comments there. If that discussion does not exist yet, +it leaves only the Actions step summary. + +`agent-daily-summary.yml` checks repository discussion settings before gathering +activity signals or resolving an agent provider. If discussions are disabled, or +the configured summary discussion category does not exist, the workflow skips +signal collection and summary generation instead of spending runtime only to +fail while posting. Cron-triggered daily summaries are disabled by default; +manual `workflow_dispatch` remains available, and repositories can enable the +cron with an `AGENT_SCHEDULE_POLICY` workflow override. + +`agent-update.yml` runs near-biweekly because GitHub cron does not support a +native every-14-days cadence. It resolves its source to the latest published +stable Sepo release tag before invoking the existing `update-agent` skill. +Manual dispatch can pass `source_ref` to test `main`, a branch, or a specific +tag. If no release exists yet, it falls back to `main` and records that fallback +in the run summary. The workflow skips when `AGENT_AUTO_UPDATE=false` or +`AGENT_SCHEDULE_POLICY` disables it. When a same-repository +`agent/update-agent-infra-*` PR is already open, the workflow keeps the runtime +checkout on the default branch, prepares the existing PR branch as the update +target, and asks the update skill to update that PR instead of opening a +duplicate. A manual `force=true` run ignores the existing PR lookup and starts +from the default branch. The canonical `self-evolving/repo` source repository +should set `AGENT_AUTO_UPDATE=false` when scheduled self-updates are not wanted; +manual dispatch remains available for explicit source ref testing. + +Single-agent routes, autonomous agent workflows, and the review synthesis step resolve their provider before installing provider CLIs. Explicit provider choices from `AGENT_DEFAULT_PROVIDER` or a route-specific override are authoritative: the workflows select that provider even when the matching repository secret is absent, so self-hosted runners can rely on local Codex or Claude authentication. When the provider is `auto`, detection uses configured provider secrets and prefers Codex when both `OPENAI_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` are present. Route-specific overrides are available by editing the relevant workflow's `resolve-agent-provider` step inline. Portal and skill jobs use non-fatal early resolution before non-agent response paths, then require a provider only immediately before invoking an agent. + +## Trigger details + +### `agent-entrypoint.yml` + +The broad pre-filter is `contains(toJSON(github.event), '@sepo-agent')`. Real mention validation happens in `agent-router.yml` through `extract-context.js`. That validation is boundary-aware and strips code blocks and quoted text before deciding whether a mention is live. + +Supported surfaces: + +| Event | Surfaces checked | +|---|---| +| `issues` | issue title, issue body | +| `issue_comment` | comment body | +| `pull_request` | PR title, PR body | +| `pull_request_review_comment` | comment body | +| `pull_request_review` | review body | +| `discussion` | discussion title, discussion body | +| `discussion_comment` | comment body | + +By default, the portal responds to `OWNER`, `MEMBER`, `COLLABORATOR`, and `CONTRIBUTOR` associations. `AGENT_ACCESS_POLICY` can tighten or widen access globally or for specific routes; public repositories that do not want prior contributors to trigger Sepo should remove `CONTRIBUTOR` from the allowlist. Bot authors are always skipped. Implicit mentions are triaged first and then checked against the resolved route, so denied requests get a visible unsupported reply instead of being dropped silently. See [Trigger access policy](../access-policy.md). + +Explicit routes are: + +- `@sepo-agent /answer` +- `@sepo-agent /implement` +- `@sepo-agent /create-action` +- `@sepo-agent /fix-pr` +- `@sepo-agent /review` +- `@sepo-agent /orchestrate` +- `@sepo-agent /skill ` + +Explicit routes skip dispatch triage and resolve locally, but still go through the same route policy checks afterward. +When an explicit `/implement` request on a pull request or discussion creates a tracking issue, the router runs a metadata-only agent prompt to synthesize the issue title and body from the request plus target context. The slash command approves the route; it is not copied into the title. Pull request metadata can also include `base_pr` for stacked or follow-up implementation requests. If metadata generation is unavailable or invalid, the issue falls back to `Implement requested change`. + +Mention-based skill requests normalize the skill name to lowercase and run +`//SKILL.md` inline through the same `skill` route used by +`agent/s/` labels. If `//setup.sh` exists, the skill +job runs it from the repository root before the agent task starts. More complex +skill setup should customize the copied `agent-router.yml` skill job directly +so repositories can use native GitHub Actions `uses`, `with`, Docker, service, +or cache features. + +### `agent-label.yml` + +Applying one of these labels triggers the same downstream routing stack without requiring a live mention: + +- `agent/answer` +- `agent/implement` +- `agent/create-action` +- `agent/fix-pr` +- `agent/review` +- `agent/orchestrate` +- `agent/s/` + +Run `Agent / Onboarding / Check Setup` after installing Sepo to create the +built-in labels. The workflow also opens or updates a `Sepo setup check` issue +with auth/provider readiness, memory and rubrics branch status, and copyable +commands for first test runs. Skill labels still use `agent/s/` and are +created per skill as needed. + +After a label-triggered request is accepted by the router, `agent-label.yml` removes the triggering `agent/*` label so label-based runs behave like one-shot queue entries, including policy-denied requests that resolve to `unsupported`. + +Built-in labels map directly to the existing routes. `agent/s/` runs +`//SKILL.md` inline; if the skill file is missing, the runner +posts a visible fallback comment instead of silently skipping the label. + +If `AGENT_STATUS_LABEL_ENABLED=true`, accepted non-unsupported issue and pull request requests also get the fixed `agent` status label. This status label is separate from the `agent/*` trigger labels and does not select a route. + +Label triggers authorize the label applier rather than the issue or pull request author. Personal-repository owners map to `OWNER`; visible organization members map to `MEMBER`; repository collaborators with label permission map to `COLLABORATOR`. + +Skill names are normalized to lowercase, so `agent/s/Release-Notes` resolves to +`.skills/release-notes/SKILL.md` by default. Skill directories should use +lowercase names to match consistently across case-sensitive filesystems. + +### `agent-self-approve.yml` + +Self-approval is disabled unless `AGENT_ALLOW_SELF_APPROVE=true`. The manual +workflow accepts a pull request number, confirms the target is an open PR, and +requires latest trusted review synthesis from the authenticated Sepo actor for +the current reviewed-head marker before it runs an approval agent. Normal runs +require that synthesis to be `SHIP`; orchestrated review `HUMAN_DECISION` +handoffs may also run the agent as a decision gate for non-`SHIP` verdicts. The +agent runs with read-approved permissions and returns structured JSON with a +verdict, reason, optional follow-up context, and `inspected_head_sha`. + +Deterministic resolver code is the only part that can submit the GitHub +approval. It rereads the current PR head, rechecks trusted current-head review +provenance, verifies the approval actor differs from the pull request author, +parses the agent verdict, and approves only when the expected, current, and +inspected head SHAs match and the latest trusted current-head review synthesis +verdict is `SHIP`. Non-approval outcomes post a compact PR status comment. In +orchestrated chains, `SHIP` review synthesis and review syntheses that recommend +`HUMAN_DECISION` can hand off to `agent-self-approve`; non-`SHIP` +`HUMAN_DECISION` runs let self-approval request changes or block, but the +resolver cannot submit approval without trusted current-head `SHIP` provenance. +A self-approval `REQUEST_CHANGES` result can hand off to `fix-pr` with the +approval agent's handoff context. Self-approval status comments are upserted by +marker against comments authored by the authenticated Sepo actor, and result +artifacts are retained for failed or blocked resolution paths where available. + +### `agent-self-merge.yml` + +Self-merge is disabled unless `AGENT_ALLOW_SELF_MERGE=true`. The workflow is +deterministic: it reads the current PR metadata, requires a trusted Sepo +self-approval review for the current head SHA, blocks requested-changes and +failed-check states, marks draft PRs ready, then merges into the PR's configured +base when GitHub reports it mergeable. If checks are still pending and GitHub +reports an eligible merge state, it enables GitHub auto-merge instead. + +The final merge and auto-merge commands use `--match-head-commit` with the +approved head SHA, so a push after preflight cannot merge an unapproved head. +Self-merge status comments are marker-upserted against comments authored by the +authenticated Sepo actor. In orchestrated chains, an `agent-self-approve` +`APPROVED` result can hand off to `agent-self-merge` only when self-merge is +also enabled. + +### `agent-approve.yml` + +Approval comments on issues or discussions are matched by `@sepo-agent /approve `. The workflow finds the unresolved request marker, creates an issue when required, and dispatches the encoded workflow. + +The pending request data lives in a `` marker. Approval comments are checked against `AGENT_ACCESS_POLICY` using the route stored in that marker. For `implement` routes from non-issue surfaces, approval creates the issue from the marker's `issue_title` and `issue_body` before dispatching. diff --git a/.agent/docs/assets/sepo-overview.png b/.agent/docs/assets/sepo-overview.png new file mode 100644 index 0000000..c2a49bb Binary files /dev/null and b/.agent/docs/assets/sepo-overview.png differ diff --git a/.agent/docs/customization/configuration-list.md b/.agent/docs/customization/configuration-list.md new file mode 100644 index 0000000..853c86e --- /dev/null +++ b/.agent/docs/customization/configuration-list.md @@ -0,0 +1,50 @@ +# Configurations list + +## Repository variables + +| Variable | Purpose | +|---|---| +| `AGENT_HANDLE` | Override the mention handle. Defaults to `@sepo-agent`. | +| `AGENT_RUNS_ON` | JSON array string for runner selection. If you are using self-hosted runners, see [Self-hosted GitHub Action runner](../deployment/self-hosted-github-action-runner.md). | +| `AGENT_DEFAULT_PROVIDER` | Default provider for single-agent runs and review synthesis: `auto`, `codex`, or `claude`. Explicit `codex` / `claude` choices are honored even without matching repository secrets, allowing self-hosted runners to use local provider authentication. `auto` chooses the first configured provider secret, preferring Codex when both secrets are present. | +| `AGENT_SESSION_BUNDLE_MODE` | Default session-bundle behavior: `auto`, `always`, or `never`. For the trade-offs behind this setting, see [Session continuity](../technical-details/session-continuity.md). | +| `AGENT_AUTOMATION_MODE` | Orchestrator decision mode. Defaults to `agent` for planner-backed orchestration validated by runtime policy. Set to `heuristics` for deterministic status-based routing with lower model cost. Compatibility alias: `true` = `heuristics`; explicit `false` or legacy `disabled` values fall back to `heuristics` for explicit `/orchestrate` chains. See [Agent orchestrator](../technical-details/agent-orchestrator.md). | +| `AGENT_AUTOMATION_MAX_ROUNDS` | Maximum number of explicit orchestration handoff rounds. Defaults to `12`. | +| `AGENT_ALLOW_SELF_APPROVE` | Opt-in gate for `agent-self-approve.yml`. Defaults to `false`; when enabled, the workflow can approve only an open pull request whose current head matches a trusted `SHIP` review synthesis and the self-approval agent's inspected head. | +| `AGENT_ALLOW_SELF_MERGE` | Opt-in gate for `agent-self-merge.yml`. Defaults to `false`; when enabled with self-approval, trusted current-head self-approved PRs can be marked ready and merged into their configured base with `--match-head-commit`. | +| `AGENT_COLLAPSE_OLD_REVIEWS` | Generated comment cleanup toggle. Defaults to enabled; set to `false` to leave older AI review synthesis, rubrics review, `fix-pr` status, and orchestrator handoff comments visible instead of minimizing them as outdated. | +| `AGENT_STATUS_LABEL_ENABLED` | Set to `true` to apply the fixed `agent` status label to handled issues and pull requests. | +| `AGENT_PROJECT_MANAGEMENT_ENABLED` | Set to `true` to enable scheduled prompt-driven project-management runs. Manual runs can also use the workflow's `enabled` input. Defaults off. | +| `AGENT_PROJECT_MANAGEMENT_DRY_RUN` | Defaults project-management runs to dry-run mode. Defaults to `true`; set to `false` to apply validated managed-label plans when label application is enabled. | +| `AGENT_PROJECT_MANAGEMENT_APPLY_LABELS` | Defaults to `true`, allowing the deterministic post-agent step to update managed `priority/*` and `effort/*` labels when dry-run mode is disabled. Set to `false` to keep label application disabled even with dry-run off. | +| `AGENT_PROJECT_MANAGEMENT_POST_SUMMARY` | Set to `true` to have the final workflow step comment with the project-management summary on today's existing Daily Summary discussion. If the discussion is missing, only the Actions step summary is written. | +| `AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY` | Discussion category shared by Daily Summary discussion creation and project-management summary comments. Defaults to `General`. | +| `AGENT_PROJECT_MANAGEMENT_LIMIT` | Maximum open issues and pull requests for the agent to inspect per kind. Defaults to `100`. | +| `AGENT_AUTO_UPDATE` | Set to `false` to disable scheduled `agent-update.yml` checks. Defaults to enabled; manual workflow dispatch remains available. The canonical `self-evolving/repo` source repository should use this when scheduled self-updates are not wanted. | +| `AGENT_ACCESS_POLICY` | JSON trigger allowlist policy. See [Trigger access policy](../access-policy.md). | +| `AGENT_TASK_TIMEOUT_POLICY` | JSON policy for GitHub Actions step timeouts on agent tasks. Defaults to `{"default_minutes":30}` and accepts route overrides, for example `{"default_minutes":30,"route_overrides":{"implement":60,"review":45}}`. Values must be 1-360 minutes. | +| `AGENT_MEMORY_POLICY` | JSON policy controlling which routes can read or write repository memory. See [Repository memory](../architecture/memory.md). | +| `AGENT_MEMORY_REF` | Default branch name used when workflows mount repository memory. Defaults to `agent/memory`. | +| `AGENT_SCHEDULE_POLICY` | JSON policy controlling scheduled workflow runs. By default, scheduled daily summaries are disabled while manual dispatch remains available. See [Repository memory](../architecture/memory.md#scheduled-workflow-policy-agent_schedule_policy). | +| `AGENT_RUBRICS_POLICY` | JSON policy controlling which routes can read or write user/team rubrics. Defaults to read-only. See [User/team rubrics](../architecture/rubrics.md). | +| `AGENT_RUBRICS_REF` | Default branch name used when workflows mount user/team rubrics. Defaults to `agent/rubrics`. | +| `AGENT_RUBRICS_LIMIT` | Maximum selected rubrics injected into an agent prompt. Defaults to `10`. | +| `AGENT_COMMITTER_NAME` | Custom commit author name for implementation and PR-fix runs | +| `AGENT_COMMITTER_EMAIL` | Custom commit author email for implementation and PR-fix runs | + +The bundled workflows intentionally expose one global provider variable. If a repository needs a route-specific provider, edit that route's `resolve-agent-provider` step in the workflow YAML and set `default_provider` or `route_provider` inline. The review workflow still launches explicit Claude and Codex reviewer lanes; `AGENT_DEFAULT_PROVIDER` controls the single synthesis step that combines whatever review artifacts were produced. + +## Repository secrets + +| Secret | Purpose | +|---|---| +| Model provider secrets | | +| `OPENAI_API_KEY` | Enable Codex-backed runs on runners without local Codex authentication; also lets `AGENT_DEFAULT_PROVIDER=auto` detect Codex | +| `CLAUDE_CODE_OAUTH_TOKEN` | Enable Claude-backed runs on runners without local Claude authentication; also lets `AGENT_DEFAULT_PROVIDER=auto` detect Claude | +| GitHub auth secrets | | +| `AGENT_APP_ID` | Self-managed GitHub App ID for the bring-your-own-app path; set only with `AGENT_APP_PRIVATE_KEY`. The public Sepo App ID `3527007` is informational for hosted/OIDC usage. | +| `AGENT_APP_PRIVATE_KEY` | Self-managed GitHub App private key for the bring-your-own-app path | +| `AGENT_PAT` | PAT fallback for environments where app-based auth is not practical | + + +See [Setup guide](../deployment/setup-guide.md) for how token secrets are used. diff --git a/.agent/docs/customization/creating-your-own-actions.md b/.agent/docs/customization/creating-your-own-actions.md new file mode 100644 index 0000000..b16d57d --- /dev/null +++ b/.agent/docs/customization/creating-your-own-actions.md @@ -0,0 +1,48 @@ +# Creating your own actions + +Durable agent actions are repository-owned GitHub Actions workflows. They let a +user ask the agent to propose recurring automation, review it as a pull request, +and activate it only after merge. + +Use: + +```text +@sepo-agent /create-action create a monitoring job for ... +``` + +The route runs the normal implementation workflow with a specialized prompt. The +pull request should add or update one standalone workflow under +`.github/workflows/`, usually named `agent-action-.yml`. + +## Workflow shape + +Generated action workflows use native GitHub Actions triggers instead of a custom +`.agent/actions` scheduler. The reusable template lives at: + +```text +.agent/action-templates/agent-action-template.yml +``` + +Copy that template to `.github/workflows/agent-action-.yml` and fill +in the workflow name, cron, expiration date, lane, request text, and optional +issue-report target. + +Generated workflows should: + +- include `workflow_dispatch` for manual test runs +- include `schedule` only for automatic recurring work +- use `.github/actions/check-agent-action-expiration` before provider/runtime setup +- gate provider-backed steps with `if: steps.expiration.outputs.expired != 'true'` +- use `permission_mode: approve-all`, `memory_mode_override: read-only`, and `session_policy: track-only` for one-shot execution with run metadata +- use a unique lane such as `agent-action-` +- add `issues: write` only when setting `REPORT_ISSUE_NUMBER` for issue reporting + +GitHub does not automatically expire scheduled workflows. The shared expiration +action validates a UTC `YYYY-MM-DD` date and compares dates without GNU-only +`date -d` parsing. Use a short expiration by default, such as 30 days from +creation, unless the user asks for a different date. Extending or removing an +expired workflow should happen through normal pull request review. + +Do not generate `.agent/actions/*.yml` specs or a generic scheduler workflow. +Keep scheduling, expiration, and activation in the native workflow file so normal +PR review controls what becomes active. diff --git a/.agent/docs/customization/creating-your-own-workflows.md b/.agent/docs/customization/creating-your-own-workflows.md new file mode 100644 index 0000000..fd45272 --- /dev/null +++ b/.agent/docs/customization/creating-your-own-workflows.md @@ -0,0 +1,3 @@ +# Creating your own workflows + +[TBD] diff --git a/.agent/docs/customization/skills.md b/.agent/docs/customization/skills.md new file mode 100644 index 0000000..3a9e4fe --- /dev/null +++ b/.agent/docs/customization/skills.md @@ -0,0 +1,78 @@ +# Repository Skills + +A repository skill is a `SKILL.md` file under the configured skill root, which +defaults to `.skills`. Invoke one with `@sepo-agent /skill ` or the +`agent/s/` label. + +```text +.skills// + SKILL.md # required agent instructions + setup.sh # optional setup hook + README.md # optional human docs +``` + +Skill names are normalized to lowercase by mention and label routing, so skill +directories should use lowercase names. Reusable workflow callers can override +the root with the `skill_root` input on `agent-router.yml`; the same root is +used for skill existence checks, optional setup, and runtime prompt loading. + +## `SKILL.md` + +`SKILL.md` is the prompt fragment the agent reads after the shared Sepo base +prompt, memory prompt, and rubrics prompt. Use it for one focused capability: +required inputs, guardrails, workflow steps, validation, and final response +expectations. + +## Simple Setup + +`setup.sh` is optional. When present, Sepo runs it after the skill file is found +and before the agent task starts. Missing setup scripts are a clean no-op. + +Setup scripts run from the repository root with `bash`. Sepo exposes +`SKILL_NAME`, `SKILL_ROOT`, and `SKILL_DIR` to the script. Adding `setup.sh` is +the repository owner's opt-in to execute setup code inside the GitHub Actions +runner with the skill route's permissions. + +Example: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +npm install -g @your-org/release-notes-cli +``` + +Sepo refuses to run setup scripts on PR checkout refs so unreviewed PR heads +cannot supply executable setup. Run setup-backed skills from trusted +default-branch contexts such as an issue, discussion, issue comment, or the +`agent/s/` label flow. + +## Advanced Setup + +For setup that needs native GitHub Actions features such as `uses`, `with`, +Docker actions, services, caches, or custom containers, edit the copied +`.github/workflows/agent-router.yml` directly. The skill job has a natural +customization point around `Run skill setup` and before `Run skill`. + +Example: + +```yaml +- name: Setup release skill + if: needs.portal.outputs.skill == 'release-notes' + uses: actions/setup-node@v4 + with: + node-version: 22 +``` + +Or a Docker action: + +```yaml +- name: Setup deep research skill + if: needs.portal.outputs.skill == 'deep-research' + uses: docker://ghcr.io/example/research-env:latest + with: + args: prepare-research-env +``` + +Sepo intentionally keeps the default skill hook small instead of implementing a +second GitHub Actions language inside `.skills`. diff --git a/.agent/docs/deployment/README.md b/.agent/docs/deployment/README.md new file mode 100644 index 0000000..04a8fd5 --- /dev/null +++ b/.agent/docs/deployment/README.md @@ -0,0 +1,11 @@ +# Deployment + +This section focuses on the two main operational choices behind the `.agent` backend: + +1. **How GitHub authentication is resolved** + - [Setup guide](setup-guide.md) for full details + - [Install into an existing repository](install-existing-repository.md) for the minimal non-template path + - [Using your own GitHub App](using-your-own-github-app.md) for the supported self-managed auth path +2. **Where the workflows run** + - GitHub-hosted runners + - Use [self-hosted GitHub Action runner](self-hosted-github-action-runner.md) for faster execution and more control over the environment diff --git a/.agent/docs/deployment/install-existing-repository.md b/.agent/docs/deployment/install-existing-repository.md new file mode 100644 index 0000000..a467eea --- /dev/null +++ b/.agent/docs/deployment/install-existing-repository.md @@ -0,0 +1,117 @@ +# Install Into An Existing Repository + +This page documents the minimal path for adding the Sepo agent backend to a repository that did not start from this template. If you are starting from this repository as a template, use the main [README quick start](../../../README.md) instead. + +In practice, the cleanest install path is: + +1. open a normal PR in the target repository that adds the agent backend files +2. merge that PR +3. use the repository's own GitHub Actions workflows to bootstrap `agent/memory` and, optionally, `agent/rubrics` + +## Minimal file layout + +Copy these directories into the target repository: + +- `.agent/` +- `.github/` + +Copy the current `.github/` directory as a unit so the workflows, composite actions, and prompt templates stay in sync. + +Also merge these generated-output rules into the target repository's existing `.gitignore` without replacing target-owned entries: + +```gitignore +.agent/dist/ +.agent/node_modules/ +``` + +The workflows build `.agent/dist/` on GitHub-hosted runners. Keeping generated runtime outputs ignored prevents them from being committed accidentally. + +## Repository configuration + +At minimum, configure: + +- Issues enabled in `Settings > General > Features > Issues` +- GitHub Actions enabled in `Settings > Actions > General` +- the Sepo GitHub App installed on the selected repository +- `OPENAI_API_KEY` and/or `CLAUDE_CODE_OAUTH_TOKEN` as repository secrets + +See [Setup guide](setup-guide.md) for the auth options and trade-offs. + +## First verification + +After the files and secrets are in place: + +1. run `Agent / Onboarding / Check Setup` from GitHub Actions +2. review the `Sepo setup check` issue that the workflow opens or updates +3. run a copyable test command from that issue's status comment, or open another issue and mention `@sepo-agent` +4. wait for the `👀` reaction and the follow-up workflow run + +The onboarding workflow is safe to rerun. It creates the built-in trigger labels +(`agent/answer`, `agent/implement`, `agent/create-action`, `agent/review`, +`agent/fix-pr`, and `agent/orchestrate`) when they are missing, then updates the +same setup issue comment with GitHub auth, provider credentials, memory, rubrics, +remaining setup, and test commands. + +## Memory Setup + +### Setup memory branch from GitHub Actions + +After setting up the repo, you can manually dispatch the github action `Agent / Memory / Initialization` or run a local command to setup the memory branch. + +That workflow: + +- rejects the run if `agent/memory` already exists, so it stays a one-time initializer +- creates `agent/memory` on the runner when it does not exist yet +- seeds `PROJECT.md`, `MEMORY.md`, plus `.gitkeep` placeholders in `daily/`, `github/`, and `github///` +- commits and pushes the bootstrap branch without requiring a local checkout +- runs the initial GitHub artifact sync and recent-activity curation inline after the bootstrap commit + +The workflow reuses the same branch to populate `github///*.json`, then runs the agentic memory curation pass on top of that seeded state. + +
+ Alternative: local memory bootstrap +

If you want to create the agent/memory branch locally before the workflows do it for you:

+ 
npm --prefix .agent ci
+npm --prefix .agent run build
+npm --prefix .agent run bootstrap:memory -- --repo <owner/repo>
+git push origin agent/memory
+

If origin/agent/memory already exists and your clone predates it, run git fetch origin first so the bootstrap command can reuse the remote-tracking branch instead of starting a fresh local one.

+

That command:

+
    +
  • creates or updates a local agent/memory branch without changing your current checkout
    • +
  • reuses origin/agent/memory when it already exists locally as a remote-tracking branch, otherwise seeds a fresh branch
    • +
  • seeds PROJECT.md and MEMORY.md, plus .gitkeep placeholders in daily/, github/, and github/<owner>/<repo>/
    • +
  • commits the initialization locally when the branch needs it
    • +
+

If you skip this step, the GitHub Actions workflows above can bootstrap the branch for you.

+
+ +### Run memory workflows from actions + +Use `Agent / Memory / Initialization` only for first-time setup. It will fail if `agent/memory` already exists. + +After the branch exists, you can manually dispatch the ongoing memory workflows from GitHub Actions: + +- `Agent / Memory / Sync GitHub Artifacts` +- `Agent / Memory / Curate Recent Activity` +- `Agent / Memory / Record PR Closure` + +`Agent / Memory / Initialization` is the first-run initializer. It does not require +`agent/memory` to exist yet, but it will reject reruns once that branch has +already been created. + +## Rubrics Setup + +After setting up the repo, you can manually dispatch `Agent / Rubrics / Initialization` to create the dedicated `agent/rubrics` branch. + +That workflow: + +- rejects the run if `agent/rubrics` already exists, so it stays a one-time initializer +- creates `agent/rubrics` on the runner when it does not exist yet +- seeds the rubrics branch layout (`README.md` plus `rubrics/coding/`, `rubrics/communication/`, and `rubrics/workflow/` placeholders) +- runs a provider-backed initialization prompt that can populate initial rubrics from supplied context +- if no context is supplied, asks the agent to inspect recent merged PRs and trusted contributor feedback for durable user/team preferences +- validates rubric YAML before committing and pushing the branch +- fails if the branch cannot be committed and pushed, so first-run setup cannot silently skip persistence + +The initialization workflow accepts free-form context. Use it to point the agent at important PRs, issues, review comments, or team preferences that should shape the first rubric set. After the branch exists, use `Agent / Rubrics / Update` for ongoing rubric learning. diff --git a/.agent/docs/deployment/self-hosted-github-action-runner.md b/.agent/docs/deployment/self-hosted-github-action-runner.md new file mode 100644 index 0000000..5cc8989 --- /dev/null +++ b/.agent/docs/deployment/self-hosted-github-action-runner.md @@ -0,0 +1,28 @@ +# Self-hosted GitHub Action runner + +Self-hosted runners run GitHub Actions jobs on infrastructure you operate, such as a local Mac mini, instead of on GitHub-hosted runners. + +Self-hosted runners are a good fit when you want: + +- faster runs by avoiding repeated environment setup +- more control over security and network boundaries +- lower cost at larger scale +- extra flexibility, including richer local tooling or agent capabilities + +## Local runner setup + +For the maintained setup scripts and step-by-step instructions, use [`.agent/tools/local-runner`](../../tools/local-runner/README.md). That folder contains the host requirement check, bootstrap, setup, start, stop, cleanup, and launchd template files for running local macOS self-hosted runners. + +Keep this deployment page focused on the decision to use self-hosted runners; keep machine-specific setup details in the local runner tool folder. + +## Runner requirements + +At a high level, the runner host needs Node support compatible with `.github/actions/setup-agent-runtime`, `git`, `gh`, `jq`, `curl`, `bash`, and network access. It also needs either repository secrets for the selected agent providers or local provider authentication available to the same user that runs the GitHub runner. Docker is optional unless your workflows require it. + +## Provider auth note + +On self-hosted runners, an explicit `AGENT_DEFAULT_PROVIDER=codex` or `AGENT_DEFAULT_PROVIDER=claude` is treated as an operator choice. The provider resolver will select that provider even if the matching repository secret is absent, so single-agent runs and review synthesis can use local Codex or Claude authentication already configured on the machine. In `auto` mode, provider detection still relies on repository secrets and prefers Codex when both provider secrets are present. The review workflow still attempts explicit Claude and Codex reviewer lanes; provider resolution controls the synthesis step that combines successful reviewer outputs. + +## Continuity note + +Repositories with sticky self-hosted runners can choose to set `AGENT_SESSION_BUNDLE_MODE=never` to prefer local session state over artifact bundles. For the trade-offs behind that setting, see [Session continuity](../technical-details/session-continuity.md). diff --git a/.agent/docs/deployment/setup-guide.md b/.agent/docs/deployment/setup-guide.md new file mode 100644 index 0000000..eece065 --- /dev/null +++ b/.agent/docs/deployment/setup-guide.md @@ -0,0 +1,82 @@ +# Setup guide + +There are two main customization points: how GitHub authentication is resolved, and where the workflows run. + +## Supported GitHub auth paths + +| Path | Best when | What you configure | +|---|---|---| +| Official Sepo-hosted app via OIDC broker | You want the easiest default setup | standard workflow permissions, selected-repository Sepo GitHub App installation, and your model-provider secrets | +| Bring your own GitHub App | You want the supported self-managed path | `AGENT_APP_ID` + `AGENT_APP_PRIVATE_KEY` | +| Fine-grained PAT | App installation is blocked or you need a debugging escape hatch | `AGENT_PAT` | +| Fallback workflow token | Emergency or lowest-friction fallback | no extra secret; uses `github.token` | + +The shared action `.github/actions/resolve-github-auth` handles all four modes through a single entry point and selects them in priority order, so workflows can keep one auth path even when repositories choose different credential strategies: + +### Auth priority + +1. direct GitHub App token from `AGENT_APP_ID` + `AGENT_APP_PRIVATE_KEY` +2. official OIDC broker exchange +3. `AGENT_PAT` +4. fallback workflow token `github.token` + +## Comparing agent setups + +- **Official hosted app via OIDC broker:** the least setup, but authentication is brokered through the official hosted exchange. That means the workflow sends an auth exchange request to a public Sepo service, similar to how the [Claude Code action](https://github.com/anthropics/claude-code-action) handles user requests. +- **Bring your own GitHub App:** the best supported self-managed path; it avoids the hosted broker and gives cleaner app-based identity, but requires app setup and installation management. +- **Fine-grained PAT:** a convenient fallback, but actions are attributed to the token owner and there is less separation between human and agent identity. +- **Fallback workflow token:** the weakest long-term option for automation patterns such as agent handoffs or broader follow-up flows. + +## Official hosted app + +The public hosted app is [sepo-agent-app](https://github.com/apps/sepo-agent-app), +owned by [self-evolving](https://github.com/self-evolving). Its GitHub App ID +is `3527007`. + +In `.github/actions/resolve-github-auth`, the hosted app path: + +- requests a GitHub Actions OIDC token +- exchanges it with the official Sepo broker +- receives a short-lived GitHub App installation token + +This path is built in. It requires standard workflow permissions, the Sepo GitHub +App installed on the selected repository, and at least one model-provider secret. +Hosted users do not need repo-local `AGENT_APP_ID` / `AGENT_APP_PRIVATE_KEY` +secrets; those are only for the self-managed app path. + +For first-time setup, install the Sepo GitHub App with **Only select repositories** +and select the repository you are onboarding. **All repositories** is supported, +but it grants broader access and can trigger bootstrap checks across many +repositories, so it is not the recommended first install path. + +See [Developer notes](../technical-details/developer-notes.md#known-limitations) +for the hosted app installation limitation. + +## Bring your own GitHub App + +If you want a fully self-managed setup, configure: + +- `AGENT_APP_ID` +- `AGENT_APP_PRIVATE_KEY` + +The workflows then mint the installation token locally via `actions/create-github-app-token@v1`. + +## Personal Access Token (PAT) + +You can also configure `AGENT_PAT` as an escape hatch when app installation is blocked by policy or needed for debugging. + +If you use a fine-grained PAT, start with these repository permissions: + +- **Contents:** read and write +- **Pull requests:** read and write +- **Issues:** read and write +- **Discussions:** read and write, only if you use discussion triggers +- **Actions:** read and write, for approval dispatch and review artifact flows + +## Workflow token fallback + +If no higher-priority auth mode is configured, the backend can still fall back to `github.token`. This is useful as a lowest-friction fallback, but it should not be treated as the preferred long-term setup for more advanced automation. + +## Continuity note + +If you move to sticky self-hosted runners, also review `AGENT_SESSION_BUNDLE_MODE`. That setting is manual; the backend does not switch it automatically just because a runner is self-hosted. See [Self-hosted GitHub Action runner](self-hosted-github-action-runner.md) for the runner side of that trade-off. diff --git a/.agent/docs/deployment/using-your-own-github-app.md b/.agent/docs/deployment/using-your-own-github-app.md new file mode 100644 index 0000000..5351cfa --- /dev/null +++ b/.agent/docs/deployment/using-your-own-github-app.md @@ -0,0 +1,22 @@ +# Using your own GitHub App + +Use this path when you want a fully self-managed or self-hosted setup. Create your own GitHub App and configure: + +- `AGENT_APP_ID` +- `AGENT_APP_PRIVATE_KEY` + +With this path, workflow authentication is resolved locally through your own GitHub App installation rather than being exchanged through the official hosted OIDC broker. + +## Minimum app permissions + +For the current workflow set, the app should have at least: + +- **Contents**: read and write +- **Pull requests**: read and write +- **Issues**: read and write +- **Discussions**: read and write if you use discussion triggers +- **Actions**: read and write if you use approval dispatch, review artifacts, or related workflow-driven follow-up flows + +Using your own app is the supported way to avoid depending on the official Sepo-hosted auth broker while keeping the same workflow behavior. + +For the full auth priority and comparison against the hosted broker path, PAT fallback, and workflow token fallback, see [Setup guide](setup-guide.md). diff --git a/.agent/docs/overview/quick-start.md b/.agent/docs/overview/quick-start.md new file mode 100644 index 0000000..b9933da --- /dev/null +++ b/.agent/docs/overview/quick-start.md @@ -0,0 +1,52 @@ +# Quick Start + +## Start from the template + +1. Create a new repository with **Use this template**. Forking is supported, but forks often have Issues and/or Actions disabled by default; template-created repos usually avoid those fork-specific defaults. +2. Install the [Sepo GitHub App](https://github.com/apps/sepo-agent-app/installations/select_target). For first-time setup, choose **Only select repositories** and select the repository you are setting up. +3. Use the hosted Sepo App path unless your organization requires a self-managed GitHub App. See the [setup guide](../deployment/setup-guide.md) for details. +4. Before onboarding, confirm the repository is ready: + - **Issues** are enabled in `Settings > General > Features > Issues`. + - **Actions** are enabled in `Settings > Actions > General`. + - The Sepo GitHub App is installed for this repository. + - At least one model-provider credential is configured as a repository secret: `OPENAI_API_KEY` for Codex-backed runs or `CLAUDE_CODE_OAUTH_TOKEN` for Claude-backed runs. +5. Run `Agent / Onboarding / Check Setup` from GitHub Actions. It creates the built-in `agent/*` trigger labels if they are missing and opens or updates a `Sepo setup check` issue with configuration status and copyable test commands. +6. Open an issue and mention `@sepo-agent` in the issue body or a comment. After a short delay, the workflow should add an eyes reaction and then post a response. + +## Install into an existing repository + +Use [Install into an existing repository](../deployment/install-existing-repository.md) for the minimal non-template flow. It covers copying `.agent/` and `.github/`, configuring secrets, running the onboarding setup check, and bootstrapping `agent/memory` from GitHub Actions. + +## Trigger Sepo + +Use a free-form mention when you want the router to infer the best route: + +```md +@sepo-agent can you explain how review synthesis works? +``` + +Use an explicit slash route when you already know the action: + +| Action | Use it for | Syntax | +|---|---|---| +| Answer | Ask a question, or request plan-only procedure guidance before coding. | `@sepo-agent /answer ...` | +| Implement | Turn an issue request into a branch and draft PR. | `@sepo-agent /implement ...` | +| Create action | Propose a standalone scheduled agent workflow through a PR. | `@sepo-agent /create-action ...` | +| Review | Run the dual-agent PR review flow. | `@sepo-agent /review` | +| Fix PR | Push fixes to the current PR branch. | `@sepo-agent /fix-pr` | +| Skill | Run a repository skill from `//SKILL.md`. | `@sepo-agent /skill ` | + +You can also trigger the same built-in routes with labels: + +| Label | Route | +|---|---| +| `agent/answer` | Answer | +| `agent/implement` | Implement | +| `agent/create-action` | Create action | +| `agent/review` | Review | +| `agent/fix-pr` | Fix PR | +| `agent/s/` | Skill | + +Only authorized repository users can trigger Sepo. By default, repositories allow `OWNER`, `MEMBER`, `COLLABORATOR`, and `CONTRIBUTOR` associations; public repositories can tighten this with `AGENT_ACCESS_POLICY`. See [Trigger access policy](../access-policy.md) to customize that behavior. + +`Agent / Onboarding / Check Setup` creates the built-in labels listed above. Custom skill labels still use the `agent/s/` pattern and can be created as needed. diff --git a/.agent/docs/overview/what-is-self-evolving-repo.md b/.agent/docs/overview/what-is-self-evolving-repo.md new file mode 100644 index 0000000..4d63709 --- /dev/null +++ b/.agent/docs/overview/what-is-self-evolving-repo.md @@ -0,0 +1,28 @@ +# What is a self-evolving repository? + +Besides the code itself, a self-evolving repository also contains two things: a schema for organizing development context, and an operational layer that can act on that context. + +## 1. A schema for development artifacts + +Traditional repositories are good at storing source code, configuration, and build scripts. A self-evolving repository also needs a place and a pattern for artifacts that matter during agent-assisted development, such as: + +- memories and interaction histories +- user preferences and operating conventions +- plans, evaluations, and verification traces +- prompts, skills, and other reusable agent-facing assets + +In that sense, it plays a role similar to tools like `just`, `make`, or `cmake`: it helps organize how development work happens, not just what files exist. For agent development, this matters even more because traceability, reproducibility, and efficiency depend on preserving context in a structured and inspectable way. + +## 2. A way to run and collaborate with agents + +A self-evolving repository also needs a way to actually launch agents and work with them. In this repository, that means using GitHub-native surfaces such as: + +- mentions in issues, pull requests, and discussions +- labels and approval commands +- reusable workflows and route-specific prompts + +That operational layer lets the repository answer questions, propose changes, review pull requests, fix issues, and improve its own workflow over time. + +## From static artifact to living system + +The point is not that code becomes magical. The point is that the repository is no longer treated as only a static artifact. It becomes a living system that can accumulate context, respond to feedback, and evolve alongside development. diff --git a/.agent/docs/technical-details/agent-orchestrator.md b/.agent/docs/technical-details/agent-orchestrator.md new file mode 100644 index 0000000..fa63879 --- /dev/null +++ b/.agent/docs/technical-details/agent-orchestrator.md @@ -0,0 +1,190 @@ +# Agent orchestrator + +The orchestrator is an explicit high-level route (`/orchestrate` or `agent/orchestrate`) that evaluates current target state and dispatches the most appropriate built-in next action. + +Configure `AGENT_AUTOMATION_MODE` to choose how orchestrator handoffs are decided. The packaged entry workflows default to `agent`; set `heuristics` for deterministic routing with lower model cost: + +| Mode | Meaning | +|---|---| +| `heuristics` | Deterministic built-in state machine. | +| `agent` | Planner-assisted orchestration, validated by runtime policy. | + +Set `AGENT_AUTOMATION_MAX_ROUNDS` to cap the chain length. The default cap is 12 rounds. + +## Current heuristics state machine + +The orchestrator supports an explicit manual start plus the existing bounded handoff policy: + +```mermaid +stateDiagram-v2 + [*] --> Implement: /orchestrate on issue + [*] --> Review: /orchestrate on PR + [*] --> FixPR: /orchestrate on PR with CHANGES_REQUESTED + + Implement --> Review: success + PR created + Implement --> Stop: failed or no PR + + Review --> SelfApprove: SHIP or HUMAN_DECISION + AGENT_ALLOW_SELF_APPROVE=true + Review --> FixPR: MINOR_ISSUES / NEEDS_REWORK / CHANGES_REQUESTED without HUMAN_DECISION + Review --> Stop: SHIP or HUMAN_DECISION + self-approval disabled + Review --> Stop: failed or unsupported verdict + + SelfApprove --> FixPR: REQUEST_CHANGES + SelfApprove --> SelfMerge: approved + AGENT_ALLOW_SELF_MERGE=true + SelfApprove --> Stop: approved + self-merge disabled / blocked / failed + SelfMerge --> Stop: merged / auto_merge_enabled / blocked / failed + + FixPR --> Review: success + FixPR --> Stop: no_changes / failed / verify_failed / unsupported PR + + SelfApprove --> Stop: max rounds exhausted + Review --> Stop: max rounds exhausted + FixPR --> Stop: max rounds exhausted + Implement --> Stop: max rounds exhausted +``` + +When the route starts, the router dispatches `agent-orchestrator.yml` with: + +- source action (`orchestrate`) +- target kind (`issue` or `pull_request`) +- target number +- requester and request text +- current round and max rounds +- optional `base_branch` or `base_pr` for stacked implementation PRs + +Each action workflow launched by `agent-orchestrator.yml` receives +`orchestration_enabled: true`. Only runs with that explicit context hand back to +the orchestrator after post-processing; direct `/implement`, `/review`, and +`/fix-pr` runs, plus manual `agent-self-approve.yml` and +`agent-self-merge.yml` runs, keep the default `orchestration_enabled: false` +and stop after their own workflow. For +orchestrator-launched fix-pr runs, the completion status comment attributes the +visible request mention to the configured agent handle (`AGENT_HANDLE`, default +`@sepo-agent`) instead of re-tagging the original human requester. + +When an action-originated handoff is used, the orchestrator also accepts: + +- source action +- source conclusion +- source recommended next step, when the source is review synthesis +- target issue or pull request number +- next target number when implementation opened a pull request +- source workflow run ID for duplicate-dispatch detection +- optional source handoff context for downstream task text +- current round and max rounds +- requester and request text to carry forward + +In `heuristics` mode, manual starts use deterministic status checks: + +- issue target: dispatch `implement` +- pull request target with `CHANGES_REQUESTED`: dispatch `fix-pr` +- other open pull request targets: dispatch `review` + +In `agent` mode, a manual start can ask the planner to choose the first +orchestration step. For issue targets, the planner can dispatch `implement` +directly for a small, self-contained change on the current issue, or act as a +meta-orchestrator when a separate child issue materially helps. For direct +implementation, the planner returns `handoff` with `next_action: "implement"`, +and the dispatcher launches `agent-implement.yml` for the current issue. For PR +targets, the planner can return `handoff` with `next_action: "review"` or +`next_action: "fix-pr"` after parsing the user's request text; runtime policy +checks that the PR is open and rejects PR starts that try to dispatch +`implement` or `delegate_issue`. The planner may also return `answer`, `stop`, +or `blocked` when no follow-up workflow should run. + +For child work, the planner may return `delegate_issue`, which is an internal +command rather than a public route. The dispatcher creates or reuses one child +issue for the requested stage and dispatches `agent-orchestrator.yml` for the +child issue in heuristic mode. New agent-created child issues store a hidden +`sepo-sub-orchestrator` marker in the issue body. Existing user-authored issues +can also be adopted when the planner provides `child_issue_number`; adoption +stores the marker in an agent-authored child issue comment instead of editing or +trusting the user-authored body. After recording the trusted parent/child marker +on the parent issue, the dispatcher also best-effort links the child through +GitHub's sub-issue REST API when that endpoint is available. If the API is +unavailable or rejects the link, the marker/comment relation remains the durable +fallback and child orchestration continues. The child issue then follows the +normal bounded chain of `implement`, `review`, `fix-pr`, and, when enabled, +`agent-self-approve` and `agent-self-merge` runs. The public route remains +`/orchestrate`; the internal command keeps child delegation separate from +concrete follow-up actions such as `implement`, `review`, `fix-pr`, +`agent-self-approve`, and `agent-self-merge`. + +When the meta-orchestrator continues sequential child implementation work after +a prior child produced an open, unmerged PR, the planner should set `base_pr` to +that prior child PR unless the next child is intentionally independent. +When a stacked parent PR is merged, branch cleanup retargets open child PRs from +the merged parent branch to the parent's base branch before deleting the parent +branch. + +Child issue metadata is intentionally GitHub-visible state, not session state. +The parent issue keeps the meta planner session, while each child issue gets its +own normal issue target identity. When the child reaches a terminal stop, the +handoff dispatcher resolves the trusted child marker from the child issue body or +from agent-authored child issue comments, or through a closing issue reference in +the terminal PR body. These trust checks normalize GitHub App actor variants such +as `app/sepo-agent-app`, `sepo-agent-app[bot]`, and `sepo-agent-app` to the same +actor. It then writes a parent progress comment, dispatches the parent issue +orchestrator in agent mode with the child result, and marks the same trusted +child marker as `done`, `blocked`, or `failed`. The progress +comment includes a compact transposed Markdown table for the visible status and +a hidden resume marker so reruns can recover a pending report or skip an +already-dispatched terminal report. Child selection and adoption comments use +the same compact table style while preserving their hidden durable markers. +If terminal child metadata is found but rejected by trust checks or cannot be +safely updated, the dispatcher posts a compact stop comment on the current +terminal issue or PR with a hidden dedupe marker. Ordinary terminal PR stops +without sub-orchestrator metadata remain silent. +If the resumed parent planner decides there is no next child or action, the +parent run posts a terminal stop comment on the parent issue with the source +conclusion, target, round, reason, and hidden `sepo-agent-orchestrate-stop` +marker. Exact trusted duplicates are skipped on reruns. +When the planner returns `blocked` with `user_message` or +`clarification_request`, that same terminal comment surfaces the planner's +question directly and the chain pauses without dispatching an `answer` route. + +Initial user-launched `/orchestrate` requests validate that the requester has +access to the delegated route capability set before dispatching work. When +`AGENT_ALLOW_SELF_APPROVE=true`, that set includes `agent-self-approve`; when +both `AGENT_ALLOW_SELF_APPROVE=true` and `AGENT_ALLOW_SELF_MERGE=true`, it also +includes `agent-self-merge`. Disabled self-approval or self-merge routes are not +part of the delegated capability check. This keeps authorization at the user +boundary: child and parent resume dispatches preserve `requested_by` for +traceability, but they do not need to thread requester association and route +policy through every downstream workflow. + +When an orchestrator dispatches `implement`, it forwards any planner-provided +or explicit `base_branch` or `base_pr` input. `agent-implement.yml` then +resolves a single base branch: `base_branch` is used when set, `base_pr` +resolves to the open same-repository PR head branch, and the repository default +branch is used when neither input is present. Setting both base inputs is +rejected. + +Manual pull request starts are deterministic only in `heuristics` mode. In +`agent` mode, issue-level and pull-request-level manual starts may invoke the +planner for the first orchestration step, and action-originated handoff +envelopes use the planner path when enabled. + +In `heuristics` mode, action-originated handoff decisions still use the fixed transition policy and round budget checks. + +Review-originated `fix-pr` handoffs carry explicit task context when available. The review dispatcher derives it from the latest review synthesis action items, and heuristic mode falls back to a conservative instruction to address only unresolved review synthesis action items while ignoring optional INFO notes and metadata-only polish. When a review synthesis recommends `HUMAN_DECISION`, self-approval-enabled orchestration routes to `agent-self-approve` instead of `fix-pr` or a human stop; self-approval then decides whether to approve, request changes, or block. Manual PR `/orchestrate` starts with a `CHANGES_REQUESTED` review decision use separate context that tells `fix-pr` to address the latest unresolved requested-change review comments instead of the review-synthesis fallback. Self-approval `REQUEST_CHANGES` handoffs preserve the approval agent's handoff context as the `fix-pr` task. Self-approval `APPROVED` handoffs dispatch `agent-self-merge` only when `AGENT_ALLOW_SELF_MERGE=true`. + +In `agent` mode, the orchestrator first runs a scoped planner prompt through the same resolved-provider runtime used by other agent actions. The planner has its own `orchestrator` route and `planner` lane, so session continuation is separate from implement, review, and fix-pr sessions. The planner runs with `approve-all` tool permission so it can gather current GitHub and repository context in non-interactive workflows. It still receives read-only repository memory, selected read-only rubrics, the handoff envelope, any source handoff context, and original request, and returns JSON describing whether to stop, block, delegate a child issue, or hand off. For blocked decisions, the planner may return `user_message` or `clarification_request` to ask for missing context in the visible stop comment. For handoffs, the planner may also return `handoff_context`: explicit, action-oriented instructions for the next workflow. When the next action is `fix-pr`, the dispatcher passes that context into `agent-fix-pr.yml`, and the fix-pr prompt treats it as the selected task and constraints for the automated fix pass. The workflow uses the runtime preflight CLI to skip this planner when the max-round budget is already exhausted or the initial requester lacks delegated-route capability, and the runtime still validates planner JSON against the fixed transition policy, the issue-only direct-implement rule, and max-round budget before dispatching anything. + +When an orchestrator-launched `implement` or `fix-pr` run reports +`no_changes`, `failed`, `verify_failed`, or `unsupported`, the dispatcher stops +and posts a structured stop comment on the current target with the source +action, conclusion, target, round, reason, and source run ID. Planner-originated +parent stops use the same structured stop format. For `fix-pr`, the runtime does +not re-review automatically after those conclusions; `fix-pr` must succeed +before the chain can hand back to `review`. + +Before dispatching, the orchestrator checks for a hidden handoff marker on the destination issue or pull request. It then writes a compact visible status comment with a transposed table for source, next action, target, round, and status, plus an explicit `Task for fix-pr` block for fix-pr handoffs. The hidden marker still records the current source run, source action, destination action, target, and round. The orchestrator writes a `pending` marker, dispatches the next workflow, and updates the marker to `dispatched` after `workflow_dispatch` succeeds. After a successful dispatch, it minimizes older visible handoff marker comments from the same authenticated agent account as outdated unless `AGENT_COLLAPSE_OLD_REVIEWS=false` is set. If dispatch fails, the marker is updated to `failed` so a rerun can retry. Rerunning the same source action or orchestrator run skips fresh `pending` or `dispatched` markers instead of enqueueing a duplicate next action. A `pending` marker records its creation time; if it is older than the one-hour stale threshold, the orchestrator marks it `failed` and retries so cancelled runs do not permanently block handoff. Non-success statuses and unsupported verdicts stop the chain. + +## Permission note + +`agent-orchestrator.yml` requests `actions: write` because `workflow_dispatch` requires it, and `issues: write` to persist dedupe markers on destination issues or pull requests. + +## Extension path + +The orchestration boundary is deliberately small: richer agent planning can expand behind the same explicit route while keeping budget checks, dedupe markers, and dispatch validation in runtime code. Runtime policy should continue to enforce allowed transitions and max rounds even when a planner suggests the next action. diff --git a/.agent/docs/technical-details/developer-notes.md b/.agent/docs/technical-details/developer-notes.md new file mode 100644 index 0000000..5ac5adc --- /dev/null +++ b/.agent/docs/technical-details/developer-notes.md @@ -0,0 +1,35 @@ +# Developer notes + +## Testing + +Run the backend test suite with: + +```bash +cd .agent +npm test +``` + +Session bundle tests cover: + +- bundle mode parsing +- artifact naming +- provider session file discovery +- create and restore round trips +- checksum validation +- path escape rejection +- thread-state interactions + +For manual continuity checks, use a disposable `HOME` or container. Do not delete files from your real `~/.codex` or `~/.claude`. + +## Known limitations + +> [!NOTE] +> The hosted Sepo App path only works for repositories where the Sepo GitHub App +> is installed. If you use selected-repository installation, add each repository +> before onboarding it. + +- Workflow-level GitHub token permissions are broader than route-level `acpx` permission modes. +- Slash routes are hardcoded to `/answer`, `/implement`, `/create-action`, `/fix-pr`, `/review`, and `/skill`. +- Mention parsing does not fully handle lazy blockquote continuations or multi-backtick inline code spans. +- Implementation approval uses comments, not reactions. +- The verify chain is a lightweight post-agent check, not a full CI substitute. diff --git a/.agent/docs/technical-details/key-concepts.md b/.agent/docs/technical-details/key-concepts.md new file mode 100644 index 0000000..0eb2155 --- /dev/null +++ b/.agent/docs/technical-details/key-concepts.md @@ -0,0 +1,135 @@ +# Key concepts + +## Self-evolving repository + +The core idea is a GitHub-native agent system where the repository itself can: + +- answer questions inline +- implement approved changes +- review pull requests +- apply fixes to pull requests +- accumulate continuity across repeated runs on the same thread + +## GitHub-native agent sessions + +- Mention the agent in a GitHub issue, PR, or discussion and it answers or does the work in place. +- Agent sessions run in GitHub Actions, with no separate chat tool or external session manager required. + +## Self-evolution + +- The agent can act through GitHub workflow triggers to assess repo state and improve code or automation. +- It can also improve the supporting agent infrastructure in the repository. + +## Core runtime vocabulary + +### Route + +A route is the high-level backend behavior being run. Current first-class routes are: + +- `answer` +- `implement` +- `fix-pr` +- `review` +- `agent-self-approve` +- `agent-self-merge` +- `create-action` +- `dispatch` +- `skill` +- `rubrics-review` +- `rubrics-initialization` +- `rubrics-update` + +Routes shape prompt selection, route policy, and which workflow path the backend follows. Dedicated rubric routes operate on user/team rubrics rather than general repository memory. + +### Lane + +A lane separates continuity identity for runs that share the same target but should not reuse the same session history. Review jobs are the clearest example: Claude review, Codex review, and synthesis all use different lanes. + +### Thread key + +A thread key is the durable identity used for persistent state: + +```text +repo:target_kind:target_number:route:lane +``` + +This is what lets later runs find the right thread state and prior session records. + +## Runtime metadata + +### RuntimeEnvelope + +Every agent run receives a shared metadata envelope. + +| Field | Meaning | +|---|---| +| `schema_version` | Envelope version, currently `1` | +| `repo_slug` | Repository as `owner/repo` | +| `route` | agent action like `review`, `implement`, `fix-pr`, `answer`, `agent-self-approve`, `agent-self-merge`, `create-action`, `dispatch`, or `skill` | +| `source_kind` | Triggering surface, such as `issue_comment`, `pull_request_review`, or `workflow_dispatch` | +| `target_kind` | `issue`, `pull_request`, `discussion`, or `repository` | +| `target_number`, `target_url` | Canonical target identity. Repo-scoped runs reserve `target_number=0` and use the repository URL. | +| `request_text`, `requested_by` | User request and GitHub login | +| `approval_comment_url` | Approval comment URL, when present | +| `workflow` | Workflow file name passed by the workflow | +| `lane` | Session lane, defaults to `default` | +| `thread_key` | `repo:target_kind:target_number:route:lane` | + +The envelope is defined in `.agent/src/envelope.ts`. + +The `repository` target kind exists for repo-scoped workflows that are not anchored to a single issue, PR, or discussion. `agent-memory-scan.yml` is the current example: it still needs a stable thread identity, so it uses the same envelope shape with `target_kind=repository` and `target_number=0`. + +## Prompt template variables + +Each model prompt receives a shared set of rendered variables, including: + +- `REPO_SLUG` +- `TARGET_KIND` +- `TARGET_NUMBER` +- `TARGET_URL` +- `SOURCE_KIND` +- `REQUEST_TEXT` + +A shared base prompt from `.github/prompts/_base.md` is prepended to each route-specific template before placeholder substitution in `renderPrompt()` in `.agent/src/run.ts`. When `MEMORY_AVAILABLE == "true"`, the runtime also prepends `.github/prompts/_memory.md`; otherwise memory guidance is omitted entirely. + +Some routes also expose an explicit allowlist of supplemental env-backed prompt variables such as `MEMORY_DIR`, `MEMORY_REF`, `REVIEWS_DIR`, and the PR-fix request comment fields. Adding a new prompt variable requires updating the allowlist in `.agent/src/run.ts`. + +## Session continuity and forks + +Routes with session policies can store thread state in git refs. `track-only` +records run metadata without using a persistent named ACP conversation; resume +policies use persistent sessions and can optionally restore local agent session +files from GitHub Actions artifacts. A destination run may also be seeded from +another thread via `session_fork_from_thread_key`; explicit `/implement` uses +this to continue from the prior `answer/default` thread for the original target +when available. See [Session continuity](session-continuity.md). + +## Repository memory + +The agent composes long-lived memory across runs on a dedicated `agent/memory` branch, governed by `AGENT_MEMORY_POLICY`. Memory is agent/project continuity: what the agent learns to improve its own future work and understand the repository. See [Repository memory](../architecture/memory.md) for layout, CLIs, access modes, and safety rules. + +## User/team rubrics + +Rubrics live on a separate `agent/rubrics` branch, governed by `AGENT_RUBRICS_POLICY`. Rubrics are normative user/team preferences: what users want the agent to optimize for during implementation and what review should score against. Normal implementation and review runs read rubrics; `Agent / Rubrics / Update` is the dedicated write path. See [User/team rubrics](../architecture/rubrics.md). + +## Runtime dependencies + +The reusable workflows bootstrap the runtime in place by checking out the repository, running `.github/actions/setup-agent-runtime`, installing dependencies inside `.agent/`, building `.agent/dist/`, and optionally installing `codex` or `claude`. + +Remaining runner requirements: + +- `git`, `gh`, `jq`, `curl`, `bash`, and network access +- one GitHub auth mode +- `id-token: write` for the official hosted auth path +- `OPENAI_API_KEY` for Codex-backed workflows +- optional `CLAUDE_CODE_OAUTH_TOKEN` for Claude-backed routes + +## Tests + +The backend has both TypeScript runtime tests and workflow-oriented helper tests. + +```bash +cd .agent +npm ci +npm test +``` diff --git a/.agent/docs/technical-details/session-continuity.md b/.agent/docs/technical-details/session-continuity.md new file mode 100644 index 0000000..316b47b --- /dev/null +++ b/.agent/docs/technical-details/session-continuity.md @@ -0,0 +1,112 @@ +# Session continuity + +Persistent session continuity can optionally use GitHub Actions artifacts to carry local agent session files across runs. This is useful when the next run lands on a fresh machine and local `HOME` state is not sticky. + +## Session policies + +The shared `run-agent-task` action accepts `session_policy`: + +- `none`: run one-shot with `acpx exec` and do not write thread state +- `track-only`: run one-shot without a stable named ACP session while still updating thread state for run metadata +- `resume-best-effort`: use a persistent named ACP session when a resumable identity is available, but fall back fresh when continuity cannot be restored +- `resume-required`: use a persistent named ACP session and fail when an existing thread cannot satisfy the continuity requirement + +`track-only` intentionally does not ensure or prompt a stable named ACP session. +Codex `track-only` runs that need a `thought_level` may use a fresh per-run ACP +session to apply that option; `track-only` runs that upload debug bundles also +use a fresh per-run ACP session. Neither path reuses the target/lane session +identity. `track-only` is for jobs that need observability without +conversational continuity, such as review synthesis, reviewer lanes, +self-approval checks, and scheduled one-shot actions. + +## Session bundle modes + +The shared `run-agent-task` action accepts `session_bundle_mode`: + +- `never`: disable bundle restore and backup +- `auto`: enable restore and backup only for routes that attempt session resume +- `always`: enable restore and backup for resume policies, and upload debug-only + bundles for `track-only` + +Because `track-only` is one-shot execution, bundle modes do not restore or +download a session for it. With `session_bundle_mode: always`, `track-only` +runs may still upload a debug-only bundle, but that artifact is marked +non-restorable and is ignored by later restore and fork lookup. The shared +action also accepts `session_bundle_retention_days` with a default of `30`. + +## Session forks + +The shared `run-agent-task` action accepts `session_fork_from_thread_key` as an optional source thread. When the destination thread has no restorable bundle, `session-restore.js` can restore the source thread's last bundle and expose its `acpxSessionId` as the seed for the new destination run. After the run, normal thread-state and artifact registration happen under the destination thread key, so future runs follow the destination history. + +Fork precedence is intentionally conservative: + +1. restore/resume the destination thread when it already has a bundle +2. otherwise, restore/resume `session_fork_from_thread_key` when provided and available, but only when the destination does not already have an `acpxSessionId` +3. otherwise, continue with a fresh destination session + +If a destination bundle download fails, fork fallback is attempted only when the destination lacks a session identity; otherwise the runtime keeps the destination identity and lets normal best-effort resume handling decide whether to resume or fall back fresh. Successful fork restores are recorded as `bundle_restore_status=restored_from_fork` on the destination thread state. + +This is artifact-backed session forking rather than provider-native cloning. The source and destination can still share the underlying ACP session id, but their uploaded artifacts diverge after the destination run. It is therefore most reliable on fresh runners or when session bundle persistence is enabled. + +The first consumer is explicit `/implement`: `agent-router.yml` dispatches `agent-implement.yml` with a fork source pointing at the prior `answer/default` thread for the original target. If the router creates a new tracking issue for a PR or discussion request, the fork source still points at the original PR/discussion thread, not the new issue. + +### A detailed walkthrough of how the answer to implement fork works? + +```mermaid +flowchart TD + answer_request["User asks @agent /answer
on an issue, PR, or discussion"] + answer_run["Answer route runs
repo:target:number:answer:default"] + answer_bundle["Answer run uploads a session bundle
and stores artifact metadata in answer thread state"] + + implement_request["Later user asks @agent /implement
on the same original target"] + router["agent-router dispatches agent-implement.yml
SESSION_FORK_FROM_THREAD_KEY = repo:target:number:answer:default"] + implement_thread["Implement destination thread
repo:issue:number:implement:default"] + + has_dest_bundle{"Destination has
a restorable bundle?"} + dest_identity{"Destination already has
acpxSessionId?"} + has_answer_bundle{"Answer fork source has
bundle + session id?"} + + restore_dest["Restore destination bundle
and resume destination session"] + keep_dest_identity["Do not restore fork files
runtime keeps destination identity"] + restore_answer["Restore answer bundle
seed implement from answer session id"] + fresh["Start a fresh implement session"] + finish["After implement run
write implement thread state
upload implement bundle"] + + answer_request --> answer_run --> answer_bundle + implement_request --> router --> implement_thread --> has_dest_bundle + answer_bundle -. "source thread metadata" .-> router + has_dest_bundle -- yes --> restore_dest --> finish + has_dest_bundle -- no --> dest_identity + dest_identity -- yes --> keep_dest_identity --> finish + dest_identity -- no --> has_answer_bundle + has_answer_bundle -- yes --> restore_answer --> finish + has_answer_bundle -- no --> fresh --> finish +``` + +## Current repository behavior + +- reusable workflows and direct route workflows fall back to repository variable `AGENT_SESSION_BUNDLE_MODE` before using the built-in `auto` default +- `track-only` routes still write thread state but run as one-shot executions, so repeated review synthesis does not reuse a prior named ACP conversation +- `fix-pr` uses `resume-best-effort` so repeated fix attempts resume when a session identity is available, but can start fresh instead of deadlocking when older thread state lacks an `acpxSessionId` +- resumed orchestrator-launched `fix-pr` runs with non-empty handoff context replay the full current route prompt so the latest planner instructions are not lost to a lightweight continuation prompt +- self-hosted runners can choose to set `AGENT_SESSION_BUNDLE_MODE=never` to prefer local session state over artifact-backed continuity, but the backend does not switch this automatically + +See [Self-hosted GitHub Action runner](../deployment/self-hosted-github-action-runner.md) for the runner side of that trade-off. + +## Backed-up session files + +When bundle persistence is enabled, the runtime backs up: + +- acpx metadata: + - `~/.acpx/sessions/.json` + - `~/.acpx/sessions/.stream.ndjson` +- Codex provider state: + - `~/.codex/sessions/**/**.jsonl` +- Claude provider state: + - `~/.claude/projects/**/**.jsonl` + +## Restore behavior + +- restore is best-effort even when bundle mode is enabled +- the final continuity decision still comes from the route session policy in `run.ts` +- bundle restore bookkeeping does not create fresh thread state on a new thread diff --git a/.agent/docs/technical-details/versioning.md b/.agent/docs/technical-details/versioning.md new file mode 100644 index 0000000..8db4f98 --- /dev/null +++ b/.agent/docs/technical-details/versioning.md @@ -0,0 +1,36 @@ +# Sepo Versioning + +Sepo uses SemVer for public version labels. + +`.agent/package.json` is the canonical Sepo package/runtime version. + +`.agent/CHANGELOG.md` is the canonical Sepo changelog. + +## Policy + +- Use `v0.x.y` tags while the install, update, and bug-report contract is still pre-release. +- Bump the `0.x` minor version for meaningful agent or workflow changes. +- Bump the `0.x` patch version for bugfix-only releases. +- Use `v1.0.0-rc.N` only when the public contract is frozen and the release is truly a candidate for `v1.0.0`. +- Use `v1.0.0` for the first public stable release. + +Package versions omit the leading `v` so they remain plain SemVer. Git tags and +release refs include the leading `v`, for example `v0.1.0`. + +## Release Flow + +Release preparation automation is intentionally GitHub Actions-only, not a +public slash route. The prepare workflow is hard-gated to `self-evolving/repo` +so forks and installed repositories do not accidentally prepare upstream Sepo +releases. + +Prepare: + +- Run `Agent / Release / Prepare` manually from GitHub Actions. +- Optionally provide a SemVer `version`; if omitted, the release agent determines + the next version from `.agent/package.json`, recent changes, and this policy. +- The workflow creates or reuses a release preparation issue, then dispatches the + existing implementation workflow with the release prompt. +- The release prompt may update files, including `.agent/CHANGELOG.md`, and + open a PR, but must not create git tags, GitHub Releases, or package + publications. diff --git a/.agent/package-lock.json b/.agent/package-lock.json new file mode 100644 index 0000000..16a4c6a --- /dev/null +++ b/.agent/package-lock.json @@ -0,0 +1,850 @@ +{ + "name": "@self-evolving/sepo", + "version": "0.2.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@self-evolving/sepo", + "version": "0.2.0", + "dependencies": { + "acpx": "^0.6.1", + "yaml": "^2.8.3" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "typescript": "^5.7.0" + } + }, + "node_modules/@agentclientprotocol/sdk": { + "version": "0.20.0", + "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-0.20.0.tgz", + "integrity": "sha512-BxEHyE4MvwyOsdyVPub1vEtyrq8E0JSdjC+ckXWimY1VabFCTXdPyXv2y2Omz1j+iod7Z8oBJDXFCJptM0GBqQ==", + "peerDependencies": { + "zod": "^3.25.0 || ^4.0.0" + } + }, + "node_modules/@clack/core": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.2.0.tgz", + "integrity": "sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==", + "license": "MIT", + "dependencies": { + "fast-wrap-ansi": "^0.1.3", + "sisteransi": "^1.0.5" + } + }, + "node_modules/@clack/prompts": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-1.2.0.tgz", + "integrity": "sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==", + "license": "MIT", + "dependencies": { + "@clack/core": "1.2.0", + "fast-string-width": "^1.1.0", + "fast-wrap-ansi": "^0.1.3", + "sisteransi": "^1.0.5" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz", + "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz", + "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz", + "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz", + "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz", + "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz", + "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz", + "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz", + "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz", + "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz", + "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz", + "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz", + "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==", + "cpu": [ + "loong64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz", + "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==", + "cpu": [ + "mips64el" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz", + "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==", + "cpu": [ + "ppc64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz", + "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz", + "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==", + "cpu": [ + "s390x" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz", + "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz", + "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz", + "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz", + "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz", + "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz", + "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz", + "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz", + "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz", + "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz", + "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@types/node": { + "version": "20.19.37", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz", + "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/acpx": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/acpx/-/acpx-0.6.1.tgz", + "integrity": "sha512-qxZPbm3SKq0UqQ0sOJ0M4iTLkF9AR7+I+JE/L/UeMUU1vW5N4nUVkZHytoHTBAu7nrej6THNzCPgrIZfv9T3AA==", + "dependencies": { + "@agentclientprotocol/sdk": "^0.20.0", + "commander": "^14.0.3", + "skillflag": "^0.1.4", + "tsx": "^4.21.0", + "zod": "^4.3.6" + }, + "bin": { + "acpx": "dist/cli.js" + }, + "engines": { + "node": ">=22.12.0" + } + }, + "node_modules/b4a": { + "version": "1.8.0", + "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.0.tgz", + "integrity": "sha512-qRuSmNSkGQaHwNbM7J78Wwy+ghLEYF1zNrSeMxj4Kgw6y33O3mXcQ6Ie9fRvfU/YnxWkOchPXbaLb73TkIsfdg==", + "license": "Apache-2.0", + "peerDependencies": { + "react-native-b4a": "*" + }, + "peerDependenciesMeta": { + "react-native-b4a": { + "optional": true + } + } + }, + "node_modules/bare-events": { + "version": "2.8.2", + "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.8.2.tgz", + "integrity": "sha512-riJjyv1/mHLIPX4RwiK+oW9/4c3TEUeORHKefKAKnZ5kyslbN+HXowtbaVEqt4IMUB7OXlfixcs6gsFeo/jhiQ==", + "license": "Apache-2.0", + "peerDependencies": { + "bare-abort-controller": "*" + }, + "peerDependenciesMeta": { + "bare-abort-controller": { + "optional": true + } + } + }, + "node_modules/bare-fs": { + "version": "4.5.6", + "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-4.5.6.tgz", + "integrity": "sha512-1QovqDrR80Pmt5HPAsMsXTCFcDYr+NSUKW6nd6WO5v0JBmnItc/irNRzm2KOQ5oZ69P37y+AMujNyNtG+1Rggw==", + "license": "Apache-2.0", + "dependencies": { + "bare-events": "^2.5.4", + "bare-path": "^3.0.0", + "bare-stream": "^2.6.4", + "bare-url": "^2.2.2", + "fast-fifo": "^1.3.2" + }, + "engines": { + "bare": ">=1.16.0" + }, + "peerDependencies": { + "bare-buffer": "*" + }, + "peerDependenciesMeta": { + "bare-buffer": { + "optional": true + } + } + }, + "node_modules/bare-os": { + "version": "3.8.6", + "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.8.6.tgz", + "integrity": "sha512-l8xaNWWb/bXuzgsrlF5jaa5QYDJ9S0ddd54cP6CH+081+5iPrbJiCfBWQqrWYzmUhCbsH+WR6qxo9MeHVCr0MQ==", + "license": "Apache-2.0", + "engines": { + "bare": ">=1.14.0" + } + }, + "node_modules/bare-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/bare-path/-/bare-path-3.0.0.tgz", + "integrity": "sha512-tyfW2cQcB5NN8Saijrhqn0Zh7AnFNsnczRcuWODH0eYAXBsJ5gVxAUuNr7tsHSC6IZ77cA0SitzT+s47kot8Mw==", + "license": "Apache-2.0", + "dependencies": { + "bare-os": "^3.0.1" + } + }, + "node_modules/bare-stream": { + "version": "2.12.0", + "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.12.0.tgz", + "integrity": "sha512-w28i8lkBgREV3rPXGbgK+BO66q+ZpKqRWrZLiCdmmUlLPrQ45CzkvRhN+7lnv00Gpi2zy5naRxnUFAxCECDm9g==", + "license": "Apache-2.0", + "dependencies": { + "streamx": "^2.25.0", + "teex": "^1.0.1" + }, + "peerDependencies": { + "bare-abort-controller": "*", + "bare-buffer": "*", + "bare-events": "*" + }, + "peerDependenciesMeta": { + "bare-abort-controller": { + "optional": true + }, + "bare-buffer": { + "optional": true + }, + "bare-events": { + "optional": true + } + } + }, + "node_modules/bare-url": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.4.0.tgz", + "integrity": "sha512-NSTU5WN+fy/L0DDenfE8SXQna4voXuW0FHM7wH8i3/q9khUSchfPbPezO4zSFMnDGIf9YE+mt/RWhZgNRKRIXA==", + "license": "Apache-2.0", + "dependencies": { + "bare-path": "^3.0.0" + } + }, + "node_modules/commander": { + "version": "14.0.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz", + "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==", + "license": "MIT", + "engines": { + "node": ">=20" + } + }, + "node_modules/esbuild": { + "version": "0.27.4", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz", + "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==", + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.27.4", + "@esbuild/android-arm": "0.27.4", + "@esbuild/android-arm64": "0.27.4", + "@esbuild/android-x64": "0.27.4", + "@esbuild/darwin-arm64": "0.27.4", + "@esbuild/darwin-x64": "0.27.4", + "@esbuild/freebsd-arm64": "0.27.4", + "@esbuild/freebsd-x64": "0.27.4", + "@esbuild/linux-arm": "0.27.4", + "@esbuild/linux-arm64": "0.27.4", + "@esbuild/linux-ia32": "0.27.4", + "@esbuild/linux-loong64": "0.27.4", + "@esbuild/linux-mips64el": "0.27.4", + "@esbuild/linux-ppc64": "0.27.4", + "@esbuild/linux-riscv64": "0.27.4", + "@esbuild/linux-s390x": "0.27.4", + "@esbuild/linux-x64": "0.27.4", + "@esbuild/netbsd-arm64": "0.27.4", + "@esbuild/netbsd-x64": "0.27.4", + "@esbuild/openbsd-arm64": "0.27.4", + "@esbuild/openbsd-x64": "0.27.4", + "@esbuild/openharmony-arm64": "0.27.4", + "@esbuild/sunos-x64": "0.27.4", + "@esbuild/win32-arm64": "0.27.4", + "@esbuild/win32-ia32": "0.27.4", + "@esbuild/win32-x64": "0.27.4" + } + }, + "node_modules/events-universal": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz", + "integrity": "sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==", + "license": "Apache-2.0", + "dependencies": { + "bare-events": "^2.7.0" + } + }, + "node_modules/fast-fifo": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz", + "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==", + "license": "MIT" + }, + "node_modules/fast-string-truncated-width": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-1.2.1.tgz", + "integrity": "sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==", + "license": "MIT" + }, + "node_modules/fast-string-width": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-1.1.0.tgz", + "integrity": "sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==", + "license": "MIT", + "dependencies": { + "fast-string-truncated-width": "^1.2.0" + } + }, + "node_modules/fast-wrap-ansi": { + "version": "0.1.6", + "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.1.6.tgz", + "integrity": "sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==", + "license": "MIT", + "dependencies": { + "fast-string-width": "^1.1.0" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/get-tsconfig": { + "version": "4.13.7", + "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.13.7.tgz", + "integrity": "sha512-7tN6rFgBlMgpBML5j8typ92BKFi2sFQvIdpAqLA2beia5avZDrMs0FLZiM5etShWq5irVyGcGMEA1jcDaK7A/Q==", + "license": "MIT", + "dependencies": { + "resolve-pkg-maps": "^1.0.0" + }, + "funding": { + "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1" + } + }, + "node_modules/resolve-pkg-maps": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", + "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==", + "license": "MIT", + "funding": { + "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1" + } + }, + "node_modules/sisteransi": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz", + "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==", + "license": "MIT" + }, + "node_modules/skillflag": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/skillflag/-/skillflag-0.1.4.tgz", + "integrity": "sha512-egFg+XCF5sloOWdtzxZivTX7n4UDj5pxQoY33wbT8h+YSDjMQJ76MZUg2rXQIBXmIDtlZhLgirS1g/3R5/qaHA==", + "license": "MIT", + "dependencies": { + "@clack/prompts": "^1.0.1", + "tar-stream": "^3.1.7" + }, + "bin": { + "skill-install": "dist/bin/skill-install.js", + "skillflag": "dist/bin/skillflag.js" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/streamx": { + "version": "2.25.0", + "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.25.0.tgz", + "integrity": "sha512-0nQuG6jf1w+wddNEEXCF4nTg3LtufWINB5eFEN+5TNZW7KWJp6x87+JFL43vaAUPyCfH1wID+mNVyW6OHtFamg==", + "license": "MIT", + "dependencies": { + "events-universal": "^1.0.0", + "fast-fifo": "^1.3.2", + "text-decoder": "^1.1.0" + } + }, + "node_modules/tar-stream": { + "version": "3.1.8", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.8.tgz", + "integrity": "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ==", + "license": "MIT", + "dependencies": { + "b4a": "^1.6.4", + "bare-fs": "^4.5.5", + "fast-fifo": "^1.2.0", + "streamx": "^2.15.0" + } + }, + "node_modules/teex": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/teex/-/teex-1.0.1.tgz", + "integrity": "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==", + "license": "MIT", + "dependencies": { + "streamx": "^2.12.5" + } + }, + "node_modules/text-decoder": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/text-decoder/-/text-decoder-1.2.7.tgz", + "integrity": "sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==", + "license": "Apache-2.0", + "dependencies": { + "b4a": "^1.6.4" + } + }, + "node_modules/tsx": { + "version": "4.21.0", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz", + "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==", + "license": "MIT", + "dependencies": { + "esbuild": "~0.27.0", + "get-tsconfig": "^4.7.5" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/yaml": { + "version": "2.8.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", + "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, + "node_modules/zod": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.1.tgz", + "integrity": "sha512-a6ENMBBGZBsnlSebQ/eKCguSBeGKSf4O7BPnqVPmYGtpBYI7VSqoVqw+QcB7kPRjbqPwhYTpFbVj/RqNz/CT0Q==", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + } + } +} diff --git a/.agent/package.json b/.agent/package.json new file mode 100644 index 0000000..f4dac82 --- /dev/null +++ b/.agent/package.json @@ -0,0 +1,19 @@ +{ + "name": "@self-evolving/sepo", + "version": "0.2.0", + "private": true, + "type": "commonjs", + "scripts": { + "build": "tsc", + "bootstrap:memory": "node dist/cli/memory/bootstrap-branch.js", + "test": "npm run build && node --test $(find dist -name '*.test.js' -type f | sort) $(find scripts -path '*/test/*.test.cjs' -type f | sort)" + }, + "dependencies": { + "acpx": "^0.6.1", + "yaml": "^2.8.3" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "typescript": "^5.7.0" + } +} diff --git a/.agent/scripts/post-agent-verify.sh b/.agent/scripts/post-agent-verify.sh new file mode 100644 index 0000000..bb1d44d --- /dev/null +++ b/.agent/scripts/post-agent-verify.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Lightweight post-agent verification for generated workflow, runtime, and +# script changes. This intentionally stays small and repo-local. + +history_changed_files="" +if [ -n "${VERIFY_BASE_SHA:-}" ]; then + if git rev-parse --verify --quiet "${VERIFY_BASE_SHA}^{commit}" >/dev/null; then + git diff --check "${VERIFY_BASE_SHA}..HEAD" + history_changed_files="$(git diff --name-only "${VERIFY_BASE_SHA}..HEAD")" + else + echo "VERIFY_BASE_SHA does not resolve to a commit; cannot run history-aware verification." >&2 + exit 1 + fi +fi + +git diff --check + +changed_files="$( + { + printf '%s\n' "$history_changed_files" + git diff --name-only + git ls-files --others --exclude-standard + } | sed '/^$/d' | sort -u +)" + +if printf '%s\n' "$changed_files" | grep -q '^\.github/workflows/'; then + ruby -e 'require "yaml"; Dir[".github/workflows/*.yml"].sort.each { |file| YAML.load_file(file) }' +fi + +if printf '%s\n' "$changed_files" | grep -qE '^(\.agent/scripts/|\.agent/src/|\.agent/package(-lock)?\.json|\.agent/tsconfig\.json)'; then + if [ -f .agent/package.json ] && [ -f .agent/tsconfig.json ]; then + ( + cd .agent + npm ci + npm run build + ) + fi + + test_files="$(find .agent/scripts -path '*/test/*.test.cjs' -type f | sort)" + if [ -n "$test_files" ]; then + node --test $test_files + fi +fi diff --git a/.agent/scripts/resolve-discussion-post-gate.sh b/.agent/scripts/resolve-discussion-post-gate.sh new file mode 100755 index 0000000..b648fe0 --- /dev/null +++ b/.agent/scripts/resolve-discussion-post-gate.sh @@ -0,0 +1,143 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Pre-runtime discussion posting gate. +# +# Daily summary generation is only useful when the target repository can accept +# the summary discussion. Keep this as shell so the workflow can run it before +# setup-agent-runtime builds the TypeScript CLIs or installs provider tools. + +trim() { + local value="$1" + value="${value#"${value%%[![:space:]]*}"}" + value="${value%"${value##*[![:space:]]}"}" + printf '%s' "$value" +} + +write_output() { + local name="$1" + local value="$2" + if [ -z "${GITHUB_OUTPUT:-}" ]; then + return 0 + fi + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" +} + +json_bool() { + if [ "$1" = "true" ]; then + printf 'true' + else + printf 'false' + fi +} + +emit_result() { + local skip="$1" + local reason="$2" + write_output "skip" "$skip" + write_output "reason" "$reason" + + jq -n \ + --argjson skip "$(json_bool "$skip")" \ + --arg reason "$reason" \ + '{skip: $skip, reason: $reason}' +} + +fail_config() { + printf 'Invalid discussion post gate configuration: %s\n' "$1" >&2 + exit 2 +} + +main() { + local repo_slug category owner repo extra response enabled category_exists has_next_page cursor end_cursor + repo_slug="$(trim "${GITHUB_REPOSITORY:-${REPO_SLUG:-}}")" + category="$(trim "${DISCUSSION_CATEGORY:-}")" + + if [ -z "$repo_slug" ]; then + fail_config "GITHUB_REPOSITORY is required" + fi + if [ -z "$category" ]; then + fail_config "DISCUSSION_CATEGORY is required" + fi + + IFS='/' read -r owner repo extra <<< "$repo_slug" + if [ -z "${owner:-}" ] || [ -z "${repo:-}" ] || [ -n "${extra:-}" ]; then + fail_config "GITHUB_REPOSITORY must be owner/repo (got: ${repo_slug})" + fi + + cursor="" + while :; do + local gh_args=(-F "owner=${owner}" -F "repo=${repo}") + if [ -n "$cursor" ]; then + gh_args+=(-F "cursor=${cursor}") + fi + + response="$( + gh api graphql \ + "${gh_args[@]}" \ + -f query=' + query($owner: String!, $repo: String!, $cursor: String) { + repository(owner: $owner, name: $repo) { + hasDiscussionsEnabled + discussionCategories(first: 100, after: $cursor) { + nodes { name } + pageInfo { + hasNextPage + endCursor + } + } + } + } + ' + )" + + if ! printf '%s' "$response" | jq -e '.data.repository | type == "object"' >/dev/null; then + printf 'Repository not found or GraphQL response was malformed for %s\n' "$repo_slug" >&2 + exit 1 + fi + + enabled="$(printf '%s' "$response" | jq -r '.data.repository.hasDiscussionsEnabled == true')" + if [ "$enabled" != "true" ]; then + emit_result "true" "repository discussions are disabled" + return 0 + fi + + category_exists="$( + printf '%s' "$response" | + jq -r --arg category "$category" ' + [.data.repository.discussionCategories.nodes[]?.name] | any(. == $category) + ' + )" + if [ "$category_exists" = "true" ]; then + emit_result "false" "discussion posting is available" + return 0 + fi + + has_next_page="$( + printf '%s' "$response" | + jq -r '.data.repository.discussionCategories.pageInfo.hasNextPage == true' + )" + if [ "$has_next_page" != "true" ]; then + break + fi + + end_cursor="$( + printf '%s' "$response" | + jq -r '.data.repository.discussionCategories.pageInfo.endCursor // ""' + )" + if [ -z "$end_cursor" ]; then + printf 'GraphQL response was malformed: discussion category page has no endCursor\n' >&2 + exit 1 + fi + cursor="$end_cursor" + done + + emit_result "true" "discussion category '${category}' was not found" +} + +main "$@" diff --git a/.agent/scripts/resolve-pending-update-pr.sh b/.agent/scripts/resolve-pending-update-pr.sh new file mode 100644 index 0000000..5e0ba19 --- /dev/null +++ b/.agent/scripts/resolve-pending-update-pr.sh @@ -0,0 +1,120 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Pre-runtime resolver for the scheduled Sepo update workflow. It detects an +# open update PR so recurring runs can update that PR instead of opening a +# duplicate. + +DEFAULT_UPDATE_BRANCH_PREFIX="agent/update-agent-infra-" + +trim() { + local value="$1" + value="${value#"${value%%[![:space:]]*}"}" + value="${value%"${value##*[![:space:]]}"}" + printf '%s' "$value" +} + +lower() { + printf '%s' "$1" | tr '[:upper:]' '[:lower:]' +} + +write_output() { + local name="$1" + local value="$2" + if [ -z "${GITHUB_OUTPUT:-}" ]; then + return 0 + fi + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" +} + +fail_config() { + printf 'Invalid pending update PR gate configuration: %s\n' "$1" >&2 + exit 2 +} + +is_true() { + case "$(lower "$(trim "$1")")" in + true|1|yes|y) return 0 ;; + *) return 1 ;; + esac +} + +json_bool() { + if [ "$1" = "true" ]; then + printf 'true' + else + printf 'false' + fi +} + +emit_result() { + local skip="$1" + local reason="$2" + local pr_url="${3:-}" + local pr_number="${4:-}" + local branch="${5:-}" + local found="${6:-false}" + + write_output "skip" "$skip" + write_output "reason" "$reason" + write_output "pr_url" "$pr_url" + write_output "pr_number" "$pr_number" + write_output "branch" "$branch" + write_output "found" "$found" + + jq -n \ + --argjson skip "$(json_bool "$skip")" \ + --argjson found "$(json_bool "$found")" \ + --arg reason "$reason" \ + --arg prUrl "$pr_url" \ + --arg prNumber "$pr_number" \ + --arg branch "$branch" \ + '{skip: $skip, found: $found, reason: $reason, prUrl: $prUrl, prNumber: $prNumber, branch: $branch}' +} + +main() { + local repo prefix prs match pr_url pr_number branch + repo="$(trim "${GITHUB_REPOSITORY:-${REPO_SLUG:-}}")" + prefix="$(trim "${UPDATE_BRANCH_PREFIX:-$DEFAULT_UPDATE_BRANCH_PREFIX}")" + + if [ -z "$repo" ]; then + fail_config "GITHUB_REPOSITORY or REPO_SLUG is required" + fi + if [ -z "$prefix" ]; then + fail_config "UPDATE_BRANCH_PREFIX cannot be empty" + fi + + if is_true "${IGNORE_EXISTING_UPDATE_PR:-${ALLOW_EXISTING_UPDATE_PR:-false}}"; then + emit_result "false" "pending update PR override enabled" + return 0 + fi + + prs="$(gh pr list \ + --repo "$repo" \ + --state open \ + --limit 100 \ + --json number,url,headRefName,isCrossRepository)" + + match="$( + printf '%s' "$prs" | + jq -c --arg prefix "$prefix" \ + '[.[] | select((.isCrossRepository | not) and (.headRefName | startswith($prefix)))][0] // empty' + )" + + if [ -z "$match" ]; then + emit_result "false" "no pending update PR" + return 0 + fi + + pr_url="$(printf '%s' "$match" | jq -r '.url // ""')" + pr_number="$(printf '%s' "$match" | jq -r '(.number // "") | tostring')" + branch="$(printf '%s' "$match" | jq -r '.headRefName // ""')" + emit_result "false" "existing update PR will be updated" "$pr_url" "$pr_number" "$branch" "true" +} + +main "$@" diff --git a/.agent/scripts/resolve-scheduled-activity-gate.sh b/.agent/scripts/resolve-scheduled-activity-gate.sh new file mode 100755 index 0000000..10affb8 --- /dev/null +++ b/.agent/scripts/resolve-scheduled-activity-gate.sh @@ -0,0 +1,287 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Pre-runtime scheduled workflow gate. +# +# This intentionally lives as a plain shell script instead of .agent/src/cli: +# scheduled workflows call it before setup-agent-runtime runs npm install/build +# or installs provider CLIs. That lets AGENT_SCHEDULE_POLICY=disabled skip cron +# work before provider/runtime setup can fail or spend time. + +SCHEDULE_MODES="always_run skip_no_updates disabled" +DEFAULT_SCHEDULE_MODE="skip_no_updates" +STATE_FILENAME="state.json" + +trim() { + local value="$1" + value="${value#"${value%%[![:space:]]*}"}" + value="${value%"${value##*[![:space:]]}"}" + printf '%s' "$value" +} + +lower() { + printf '%s' "$1" | tr '[:upper:]' '[:lower:]' +} + +write_output() { + local name="$1" + local value="$2" + if [ -z "${GITHUB_OUTPUT:-}" ]; then + return 0 + fi + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" +} + +fail_config() { + printf 'Invalid scheduled activity gate configuration: %s\n' "$1" >&2 + exit 2 +} + +is_valid_mode() { + case "$1" in + always_run|skip_no_updates|disabled) return 0 ;; + *) return 1 ;; + esac +} + +normalize_mode() { + local value="$1" + local label="$2" + local normalized + normalized="$(lower "$(trim "$value")")" + if ! is_valid_mode "$normalized"; then + fail_config "${label} must be one of ${SCHEDULE_MODES// /, } (got ${normalized:-empty})" + fi + printf '%s' "$normalized" +} + +normalize_workflow() { + lower "$(trim "$1")" +} + +resolve_mode() { + local policy_text workflow default_mode override_mode + policy_text="$(trim "${AGENT_SCHEDULE_POLICY:-}")" + workflow="$(normalize_workflow "${WORKFLOW_FILENAME:-}")" + default_mode="$DEFAULT_SCHEDULE_MODE" + override_mode="" + + if [ -z "$policy_text" ]; then + if [ "$workflow" = "agent-daily-summary.yml" ]; then + printf 'disabled' + elif [ "$workflow" = "agent-memory-sync.yml" ]; then + printf 'always_run' + else + printf '%s' "$DEFAULT_SCHEDULE_MODE" + fi + return 0 + fi + + if ! printf '%s' "$policy_text" | jq -e 'type == "object"' >/dev/null 2>&1; then + fail_config "Schedule policy must be a JSON object" + fi + + if [ "$(printf '%s' "$policy_text" | jq -r 'has("default_mode")')" = "true" ]; then + local raw_default + raw_default="$(printf '%s' "$policy_text" | jq -r 'if .default_mode == null then "" else (.default_mode | tostring) end')" + if ! default_mode="$(normalize_mode "$raw_default" "default_mode")"; then + return 2 + fi + fi + + if [ "$(printf '%s' "$policy_text" | jq -r 'has("workflow_overrides")')" = "true" ]; then + if ! printf '%s' "$policy_text" | jq -e '.workflow_overrides | type == "object"' >/dev/null 2>&1; then + fail_config "workflow_overrides must be an object" + fi + + while IFS=$'\t' read -r raw_key raw_value; do + [ -n "$raw_key" ] || continue + local key mode + key="$(normalize_workflow "$raw_key")" + if [[ ! "$key" =~ ^[a-z0-9][a-z0-9._-]*\.ya?ml$ ]]; then + fail_config "Invalid workflow override key in schedule policy: ${key:-missing}" + fi + if ! mode="$(normalize_mode "$raw_value" "workflow_overrides.${key}")"; then + return 2 + fi + if [ -n "$workflow" ] && [ "$key" = "$workflow" ]; then + override_mode="$mode" + fi + done < <( + printf '%s' "$policy_text" | + jq -r '.workflow_overrides | to_entries[] | [.key, (if .value == null then "" else (.value | tostring) end)] | @tsv' + ) + fi + + if [ -n "$override_mode" ]; then + printf '%s' "$override_mode" + elif [ "$workflow" = "agent-daily-summary.yml" ]; then + printf 'disabled' + else + printf '%s' "$default_mode" + fi +} + +json_bool() { + if [ "$1" = "true" ]; then + printf 'true' + else + printf 'false' + fi +} + +emit_result() { + local skip="$1" + local mode="$2" + local reason="$3" + local dependency_value="${4:-}" + local self_value="${5:-}" + + write_output "skip" "$skip" + write_output "mode" "$mode" + write_output "reason" "$reason" + write_output "dependency_value" "$dependency_value" + write_output "self_value" "$self_value" + + jq -n \ + --arg mode "$mode" \ + --argjson skip "$(json_bool "$skip")" \ + --arg reason "$reason" \ + --arg dependencyValue "$dependency_value" \ + --arg selfValue "$self_value" \ + '{mode: $mode, skip: $skip, reason: $reason, dependencyValue: $dependencyValue, selfValue: $selfValue}' +} + +resolve_remote_target() { + local remote="$1" + local repo token + repo="${GITHUB_REPOSITORY:-${REPO_SLUG:-}}" + token="${INPUT_GITHUB_TOKEN:-${GH_TOKEN:-}}" + if [ -n "$repo" ] && [ -n "$token" ]; then + printf 'https://x-access-token:%s@github.com/%s.git' "$token" "$repo" + else + printf '%s' "$remote" + fi +} + +fetch_json_state() { + local ref="$1" + local cwd="$2" + local fetch_target fetch_log json + fetch_target="$(resolve_remote_target origin)" + fetch_log="$(mktemp "${RUNNER_TEMP:-/tmp}/scheduled-gate-fetch.XXXXXX.log")" + + if ! git -C "$cwd" fetch --no-tags "$fetch_target" "+${ref}:${ref}" >/dev/null 2>"$fetch_log"; then + if grep -Eiq "couldn't find remote ref|no matching remote head" "$fetch_log"; then + rm -f "$fetch_log" + return 0 + fi + cat "$fetch_log" >&2 || true + rm -f "$fetch_log" + return 1 + fi + rm -f "$fetch_log" + + if ! json="$(git -C "$cwd" cat-file blob "${ref}:${STATE_FILENAME}" 2>/dev/null)"; then + return 0 + fi + if ! printf '%s' "$json" | jq -e 'type == "object"' >/dev/null 2>&1; then + return 0 + fi + printf '%s' "$json" +} + +read_field() { + local json="$1" + local field="$2" + if [ -z "$json" ] || [ -z "$field" ]; then + return 0 + fi + printf '%s' "$json" | jq -r --arg field "$field" 'if (.[$field] | type) == "string" then .[$field] else "" end' +} + +parse_time() { + local value="$1" + if [ -z "$value" ]; then + return 0 + fi + # jq's fromdateiso8601 does not accept fractional seconds on the + # GitHub-hosted runner version, while Date#toISOString() emits them. + # Normalize second-precision before parsing so persisted schedule cursors + # such as 2026-04-27T10:00:00.123Z remain usable by the pre-runtime gate. + jq -nr --arg value "$value" '($value | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601?) // empty' +} + +main() { + local mode base_dependency base_self event activity_count count_number + if ! mode="$(resolve_mode)"; then + exit 2 + fi + base_dependency="" + base_self="" + event="${GITHUB_EVENT_NAME:-}" + + if [ "$event" != "schedule" ]; then + emit_result "false" "$mode" "non-scheduled run" "$base_dependency" "$base_self" + return 0 + fi + if [ "$mode" = "disabled" ]; then + emit_result "true" "$mode" "schedule policy disabled workflow" "$base_dependency" "$base_self" + return 0 + fi + if [ "$mode" = "always_run" ]; then + emit_result "false" "$mode" "schedule policy always_run" "$base_dependency" "$base_self" + return 0 + fi + + activity_count="$(trim "${ACTIVITY_COUNT:-}")" + if [ -n "$activity_count" ]; then + count_number="$(jq -nr --arg value "$activity_count" 'try ($value | tonumber) catch empty')" + if [ -z "$count_number" ]; then + emit_result "false" "$mode" "invalid activity count" "$base_dependency" "$base_self" + return 0 + fi + if jq -en --argjson count "$count_number" '$count <= 0' >/dev/null; then + emit_result "true" "$mode" "activity count is zero" "$base_dependency" "$base_self" + return 0 + fi + emit_result "false" "$mode" "activity count is nonzero" "$base_dependency" "$base_self" + return 0 + fi + + local dependency_ref dependency_field self_ref self_field cwd dependency_json self_json dependency_value self_value dependency_time self_time + dependency_ref="${DEPENDENCY_REF:-}" + dependency_field="${DEPENDENCY_FIELD:-}" + self_ref="${SELF_REF:-}" + self_field="${SELF_FIELD:-}" + + if [ -z "$dependency_ref" ] || [ -z "$dependency_field" ] || [ -z "$self_ref" ] || [ -z "$self_field" ]; then + emit_result "false" "$mode" "missing activity cursor configuration" "$base_dependency" "$base_self" + return 0 + fi + + cwd="${GITHUB_WORKSPACE:-$(pwd)}" + dependency_json="$(fetch_json_state "$dependency_ref" "$cwd")" + self_json="$(fetch_json_state "$self_ref" "$cwd")" + dependency_value="$(read_field "$dependency_json" "$dependency_field")" + self_value="$(read_field "$self_json" "$self_field")" + dependency_time="$(parse_time "$dependency_value")" + self_time="$(parse_time "$self_value")" + + if [ -z "$dependency_time" ] || [ -z "$self_time" ]; then + emit_result "false" "$mode" "missing or invalid activity cursor" "$dependency_value" "$self_value" + return 0 + fi + if [ "$dependency_time" -le "$self_time" ]; then + emit_result "true" "$mode" "dependency cursor has not advanced" "$dependency_value" "$self_value" + return 0 + fi + emit_result "false" "$mode" "dependency cursor advanced" "$dependency_value" "$self_value" +} + +main "$@" diff --git a/.agent/scripts/resolve-update-source.sh b/.agent/scripts/resolve-update-source.sh new file mode 100644 index 0000000..560acd0 --- /dev/null +++ b/.agent/scripts/resolve-update-source.sh @@ -0,0 +1,148 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Resolve the Sepo source revision before the update agent runs. Scheduled runs +# default to the latest stable GitHub Release tag, while manual dispatch can +# provide an explicit ref for testing branches, main, or specific tags. + +DEFAULT_UPDATE_SOURCE_REPO="self-evolving/repo" +DEFAULT_UPDATE_SOURCE_FALLBACK_REF="main" + +trim() { + local value="$1" + value="${value#"${value%%[![:space:]]*}"}" + value="${value%"${value##*[![:space:]]}"}" + printf '%s' "$value" +} + +write_output() { + local name="$1" + local value="$2" + if [ -z "${GITHUB_OUTPUT:-}" ]; then + return 0 + fi + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" +} + +json_bool() { + if [ "$1" = "true" ]; then + printf 'true' + else + printf 'false' + fi +} + +fail_config() { + printf 'Invalid update source configuration: %s\n' "$1" >&2 + exit 2 +} + +resolve_commit_sha() { + local repo="$1" + local ref="$2" + local label="$3" + local payload sha + + if ! payload="$(gh api "repos/${repo}/commits/${ref}")"; then + fail_config "could not resolve ${label} ref ${repo}@${ref}" + fi + + sha="$(printf '%s' "$payload" | jq -r '.sha // ""')" + if [ -z "$sha" ]; then + fail_config "resolved ${label} ref ${repo}@${ref} did not include a commit SHA" + fi + printf '%s' "$sha" +} + +lookup_latest_stable_release() { + local repo="$1" + local releases + + if ! releases="$(gh api "repos/${repo}/releases?per_page=100")"; then + fail_config "could not list stable releases for ${repo}" + fi + + printf '%s' "$releases" | + jq -c '[.[] | select((.draft | not) and (.prerelease | not))][0] // {}' +} + +emit_result() { + local repo="$1" + local ref="$2" + local sha="$3" + local kind="$4" + local fallback="$5" + local reason="${6:-}" + local release_url="${7:-}" + + write_output "source_repo" "$repo" + write_output "source_ref" "$ref" + write_output "source_sha" "$sha" + write_output "source_kind" "$kind" + write_output "fallback" "$fallback" + write_output "reason" "$reason" + write_output "release_url" "$release_url" + + jq -n \ + --arg repo "$repo" \ + --arg ref "$ref" \ + --arg sha "$sha" \ + --arg kind "$kind" \ + --argjson fallback "$(json_bool "$fallback")" \ + --arg reason "$reason" \ + --arg releaseUrl "$release_url" \ + '{ + sourceRepo: $repo, + sourceRef: $ref, + sourceSha: $sha, + sourceKind: $kind, + fallback: $fallback, + reason: $reason, + releaseUrl: $releaseUrl + }' +} + +main() { + local repo manual_ref fallback_ref release_json tag release_url sha reason + repo="$(trim "${UPDATE_SOURCE_REPO:-$DEFAULT_UPDATE_SOURCE_REPO}")" + manual_ref="$(trim "${UPDATE_SOURCE_REF:-}")" + fallback_ref="$(trim "${DEFAULT_UPDATE_SOURCE_REF:-$DEFAULT_UPDATE_SOURCE_FALLBACK_REF}")" + + if [ -z "$repo" ]; then + fail_config "UPDATE_SOURCE_REPO cannot be empty" + fi + if [ -z "$fallback_ref" ]; then + fail_config "DEFAULT_UPDATE_SOURCE_REF cannot be empty" + fi + + if [ -n "$manual_ref" ]; then + sha="$(resolve_commit_sha "$repo" "$manual_ref" "manual")" + emit_result "$repo" "$manual_ref" "$sha" "manual" "false" + return 0 + fi + + release_json="$(lookup_latest_stable_release "$repo")" + tag="$(printf '%s' "$release_json" | jq -r '.tag_name // ""')" + release_url="$(printf '%s' "$release_json" | jq -r '.html_url // ""')" + if [ -n "$tag" ]; then + sha="$(resolve_commit_sha "$repo" "$tag" "release")" + emit_result "$repo" "$tag" "$sha" "latest-release" "false" "" "$release_url" + return 0 + fi + + if [ "$(printf '%s' "$release_json" | jq -r 'length')" = "0" ]; then + sha="$(resolve_commit_sha "$repo" "$fallback_ref" "fallback")" + reason="no stable Sepo release found; falling back to ${fallback_ref}" + emit_result "$repo" "$fallback_ref" "$sha" "fallback-main" "true" "$reason" + return 0 + fi + + fail_config "latest stable release for ${repo} did not include tag_name" +} + +main "$@" diff --git a/.agent/src/__tests__/acpx-adapter.test.ts b/.agent/src/__tests__/acpx-adapter.test.ts new file mode 100644 index 0000000..6ead4f0 --- /dev/null +++ b/.agent/src/__tests__/acpx-adapter.test.ts @@ -0,0 +1,546 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { delimiter, join } from "node:path"; + +import { + buildAcpxArgs, + buildSessionSetupCommands, + compactSessionLog, + extractAssistantText, + parseSessionIdentity, + readSessionIdentityResult, + runAcpx, + runCommandWithFileCapture, + selectPromptForSessionOutcome, + sessionNameFromThreadKey, + tailForLog, +} from "../acpx-adapter.js"; +import { sessionModeForPolicy } from "../session-policy.js"; + +test("buildAcpxArgs puts global flags before the agent token for exec routes", () => { + const args = buildAcpxArgs({ + agent: "codex", + prompt: "review this change", + permissionMode: "approve-reads", + timeout: 90, + isExecRoute: true, + }); + + assert.deepEqual(args, [ + "--approve-reads", + "--format", + "json", + "--json-strict", + "--suppress-reads", + "--timeout", + "90", + "codex", + "exec", + "review this change", + ]); +}); + +test("buildAcpxArgs uses prompt mode with a named session for persistent routes", () => { + const args = buildAcpxArgs({ + agent: "claude", + prompt: "apply the requested fix", + permissionMode: "approve-all", + sessionName: "pull_request-38-fix-pr-default", + isExecRoute: false, + }); + + assert.deepEqual(args, [ + "--approve-all", + "--format", + "json", + "--json-strict", + "--suppress-reads", + "claude", + "prompt", + "-s", + "pull_request-38-fix-pr-default", + "apply the requested fix", + ]); +}); + +test("buildAcpxArgs keeps track-only synthesis in exec mode without a named session", () => { + const args = buildAcpxArgs({ + agent: "codex", + prompt: "synthesize current artifacts", + permissionMode: "approve-all", + sessionName: sessionNameFromThreadKey("self-evolving/repo:pull_request:267:review:synthesize"), + isExecRoute: sessionModeForPolicy("track-only") === "exec", + }); + + assert.deepEqual(args, [ + "--approve-all", + "--format", + "json", + "--json-strict", + "--suppress-reads", + "codex", + "exec", + "synthesize current artifacts", + ]); + assert.equal(args.includes("-s"), false); +}); + +test("runAcpx preserves Codex thought level for track-only exec without stable session reuse", () => { + const dir = mkdtempSync(join(tmpdir(), "acpx-track-only-test-")); + const oldPath = process.env.PATH; + const threadKey = "self-evolving/repo:pull_request:268:review:synthesize"; + const stableSessionName = sessionNameFromThreadKey(threadKey); + + try { + const acpxPath = join(dir, "acpx"); + const callsPath = join(dir, "calls.jsonl"); + writeFileSync( + acpxPath, + `#!/usr/bin/env node +const fs = require("node:fs"); +const args = process.argv.slice(2); +fs.appendFileSync(process.env.ACPX_TEST_CALLS, JSON.stringify({ args }) + "\\n"); +if (args.includes("prompt")) { + process.stdout.write([ + '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"sess-track-only","models":{"currentModelId":"gpt-5.4"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Done."}}}}', + '{"jsonrpc":"2.0","id":2,"result":{"stopReason":"end_turn"}}' + ].join("\\n") + "\\n"); +} +`, + "utf8", + ); + chmodSync(acpxPath, 0o755); + process.env.PATH = `${dir}${delimiter}${oldPath || ""}`; + + const result = runAcpx({ + agent: "codex", + prompt: "synthesize current artifacts", + cwd: process.cwd(), + sessionMode: sessionModeForPolicy("track-only"), + threadKey, + permissionMode: "approve-all", + thoughtLevel: "xhigh", + preserveExecThoughtLevel: true, + env: { ACPX_TEST_CALLS: callsPath }, + }); + + assert.equal(result.exitCode, 0); + assert.equal(result.stdout, "Done."); + assert.equal(result.sessionEnsureOutcome.kind, "fresh"); + assert.match(result.sessionName ?? "", /^pull_request-268-review-synthesize-exec-[0-9a-f]{12}$/); + assert.notEqual(result.sessionName, stableSessionName); + + const sessionName = result.sessionName!; + const calls = readFileSync(callsPath, "utf8") + .trim() + .split("\n") + .map((line) => JSON.parse(line) as { args: string[] }); + + assert.deepEqual(calls.map((call) => call.args), [ + ["codex", "sessions", "new", "--name", sessionName], + ["codex", "set", "-s", sessionName, "thought_level", "xhigh"], + ["codex", "set-mode", "-s", sessionName, "full-access"], + [ + "--approve-all", + "--format", + "json", + "--json-strict", + "--suppress-reads", + "codex", + "prompt", + "-s", + sessionName, + "synthesize current artifacts", + ], + ]); + assert.equal(calls.some((call) => call.args.includes(stableSessionName)), false); + } finally { + if (oldPath === undefined) { + delete process.env.PATH; + } else { + process.env.PATH = oldPath; + } + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("runAcpx can use a transient exec session for debug bundle capture", () => { + const dir = mkdtempSync(join(tmpdir(), "acpx-track-only-debug-test-")); + const oldPath = process.env.PATH; + const threadKey = "self-evolving/repo:pull_request:272:review:claude"; + const stableSessionName = sessionNameFromThreadKey(threadKey); + + try { + const acpxPath = join(dir, "acpx"); + const callsPath = join(dir, "calls.jsonl"); + writeFileSync( + acpxPath, + `#!/usr/bin/env node +const fs = require("node:fs"); +const args = process.argv.slice(2); +fs.appendFileSync(process.env.ACPX_TEST_CALLS, JSON.stringify({ args }) + "\\n"); +if (args.includes("prompt")) { + process.stdout.write([ + '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"sess-track-only-debug","models":{"currentModelId":"claude-sonnet"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Done."}}}}', + '{"jsonrpc":"2.0","id":2,"result":{"stopReason":"end_turn"}}' + ].join("\\n") + "\\n"); +} +`, + "utf8", + ); + chmodSync(acpxPath, 0o755); + process.env.PATH = `${dir}${delimiter}${oldPath || ""}`; + + const result = runAcpx({ + agent: "claude", + prompt: "review current artifacts", + cwd: process.cwd(), + sessionMode: sessionModeForPolicy("track-only"), + threadKey, + permissionMode: "approve-all", + preserveExecSession: true, + env: { ACPX_TEST_CALLS: callsPath }, + }); + + assert.equal(result.exitCode, 0); + assert.equal(result.stdout, "Done."); + assert.equal(result.sessionEnsureOutcome.kind, "fresh"); + assert.match(result.sessionName ?? "", /^pull_request-272-review-claude-exec-[0-9a-f]{12}$/); + assert.notEqual(result.sessionName, stableSessionName); + + const sessionName = result.sessionName!; + const calls = readFileSync(callsPath, "utf8") + .trim() + .split("\n") + .map((line) => JSON.parse(line) as { args: string[] }); + + assert.deepEqual(calls.map((call) => call.args), [ + ["claude", "sessions", "new", "--name", sessionName], + ["claude", "set-mode", "-s", sessionName, "bypassPermissions"], + [ + "--approve-all", + "--format", + "json", + "--json-strict", + "--suppress-reads", + "claude", + "prompt", + "-s", + sessionName, + "review current artifacts", + ], + ]); + assert.equal(calls.some((call) => call.args.includes(stableSessionName)), false); + } finally { + if (oldPath === undefined) { + delete process.env.PATH; + } else { + process.env.PATH = oldPath; + } + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("selectPromptForSessionOutcome uses continuation only after successful resume", () => { + assert.equal( + selectPromptForSessionOutcome({ + fullPrompt: "full route prompt", + continuationPrompt: "latest request only", + outcome: { kind: "resumed", resumedFromSessionId: "ses-123" }, + }), + "latest request only", + ); + + assert.equal( + selectPromptForSessionOutcome({ + fullPrompt: "full route prompt", + continuationPrompt: "latest request only", + outcome: { kind: "resume_fallback", resumedFromSessionId: "ses-123", error: "expired" }, + }), + "full route prompt", + ); + + assert.equal( + selectPromptForSessionOutcome({ + fullPrompt: "full route prompt", + continuationPrompt: "latest request only", + outcome: { kind: "fresh" }, + }), + "full route prompt", + ); +}); + +test("selectPromptForSessionOutcome falls back to full prompt without continuation", () => { + assert.equal( + selectPromptForSessionOutcome({ + fullPrompt: "full route prompt", + outcome: { kind: "resumed", resumedFromSessionId: "ses-123" }, + }), + "full route prompt", + ); +}); + +test("buildSessionSetupCommands configures thought level and full-access mode for persistent sessions", () => { + const commands = buildSessionSetupCommands({ + agent: "codex", + sessionName: "issue-24-implement-default", + thoughtLevel: "xhigh", + permissionMode: "approve-all", + }); + + assert.deepEqual(commands, [ + { + label: "set thought_level", + args: ["codex", "set", "-s", "issue-24-implement-default", "thought_level", "xhigh"], + }, + { + label: "set-mode", + args: ["codex", "set-mode", "-s", "issue-24-implement-default", "full-access"], + }, + ]); +}); + +test("buildSessionSetupCommands sets full-access mode for all persistent sessions", () => { + const commands = buildSessionSetupCommands({ + agent: "codex", + sessionName: "pull_request-38-review-default", + thoughtLevel: "high", + permissionMode: "approve-all", + }); + + assert.deepEqual(commands, [ + { + label: "set thought_level", + args: ["codex", "set", "-s", "pull_request-38-review-default", "thought_level", "high"], + }, + { + label: "set-mode", + args: ["codex", "set-mode", "-s", "pull_request-38-review-default", "full-access"], + }, + ]); +}); + +test("buildSessionSetupCommands does nothing without a session and ignores blank thought level", () => { + assert.deepEqual( + buildSessionSetupCommands({ + agent: "codex", + sessionName: undefined, + thoughtLevel: "xhigh", + permissionMode: "approve-all", + }), + [], + ); + + assert.deepEqual( + buildSessionSetupCommands({ + agent: "codex", + sessionName: "issue-24-answer-default", + thoughtLevel: " ", + permissionMode: "approve-all", + }), + [ + { + label: "set-mode", + args: ["codex", "set-mode", "-s", "issue-24-answer-default", "full-access"], + }, + ], + ); +}); + +test("buildSessionSetupCommands maps claude approve-all to bypassPermissions only", () => { + const commands = buildSessionSetupCommands({ + agent: "claude", + sessionName: "pull_request-81-review-default", + thoughtLevel: "max", + permissionMode: "approve-all", + }); + + assert.deepEqual(commands, [ + { + label: "set-mode", + args: ["claude", "set-mode", "-s", "pull_request-81-review-default", "bypassPermissions"], + }, + ]); +}); + +test("buildSessionSetupCommands skips claude setup when not approve-all", () => { + const commands = buildSessionSetupCommands({ + agent: "claude", + sessionName: "pull_request-81-review-default", + thoughtLevel: "max", + permissionMode: "approve-reads", + }); + + assert.deepEqual(commands, []); +}); + +test("extractAssistantText returns the last message from a compacted log", () => { + const log = [ + '{"type":"message","text":"Checking the repo."}', + '{"type":"tool_call","name":"shell","status":"completed"}', + '{"type":"message","text":"The answer is four."}', + '{"type":"done","stopReason":"end_turn"}', + ].join("\n"); + + assert.equal(extractAssistantText(log), "The answer is four."); +}); + +test("extractAssistantText returns empty string when no messages exist", () => { + const log = '{"type":"done","stopReason":"end_turn"}'; + assert.equal(extractAssistantText(log), ""); +}); + +test("tailForLog leaves short values unchanged", () => { + assert.equal(tailForLog("hello", 10), "hello"); +}); + +test("tailForLog keeps the end of long values with a truncation marker", () => { + const value = "abcdefghijklmnopqrstuvwxyz"; + assert.equal( + tailForLog(value, 10), + "[truncated 16 chars]\nqrstuvwxyz", + ); +}); + +test("runCommandWithFileCapture captures large stdout without a maxBuffer cap", () => { + const size = 2 * 1024 * 1024; + const result = runCommandWithFileCapture({ + command: process.execPath, + args: ["-e", `process.stdout.write("x".repeat(${size}))`], + cwd: process.cwd(), + }); + + assert.equal(result.exitCode, 0); + assert.equal(result.stderr, ""); + assert.equal(result.stdout.length, size); + assert.equal(result.stdout, "x".repeat(size)); +}); + +test("runCommandWithFileCapture captures stderr and failing exit codes", () => { + const result = runCommandWithFileCapture({ + command: process.execPath, + args: ["-e", 'process.stderr.write("oops\\n"); process.exit(7);'], + cwd: process.cwd(), + }); + + assert.equal(result.exitCode, 7); + assert.equal(result.stdout, ""); + assert.equal(result.stderr, "oops\n"); +}); + +test("runCommandWithFileCapture treats signal-terminated processes as failures", () => { + const result = runCommandWithFileCapture({ + command: process.execPath, + args: ["-e", 'process.kill(process.pid, "SIGTERM")'], + cwd: process.cwd(), + }); + + assert.equal(result.exitCode, 1); +}); + +test("compactSessionLog merges tokens and keeps structured events", () => { + const ndjson = [ + '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{}}', + '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{}}}', + '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{}}', + '{"jsonrpc":"2.0","id":1,"result":{"sessionId":"sess-123","models":{"currentModelId":"gpt-5.4/xhigh"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"available_commands_update"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Check"}}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ing."}}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"tool_call","name":"shell","status":"running"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"tool_call_update","name":"shell","status":"completed"}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Done."}}}}', + '{"jsonrpc":"2.0","method":"session/update","params":{"update":{"sessionUpdate":"usage_update","used":5000,"size":100000}}}', + '{"jsonrpc":"2.0","id":2,"result":{"stopReason":"end_turn"}}', + ].join("\n"); + + const lines = compactSessionLog(ndjson).trim().split("\n").map((l) => JSON.parse(l)); + + assert.deepEqual(lines, [ + { type: "session", sessionId: "sess-123", model: "gpt-5.4/xhigh" }, + { type: "message", text: "Checking." }, + { type: "tool_call", name: "shell", status: "running" }, + { type: "tool_call_update", name: "shell", status: "completed" }, + { type: "message", text: "Done." }, + { type: "usage", used: 5000, size: 100000 }, + { type: "done", stopReason: "end_turn" }, + ]); +}); + +test("parseSessionIdentity reads canonical acpx json output", () => { + const identity = parseSessionIdentity(JSON.stringify({ + acpxRecordId: "record-123", + acpSessionId: "session-456", + agentSessionId: "inner-789", + })); + + assert.deepEqual(identity, { + acpxRecordId: "record-123", + acpxSessionId: "session-456", + }); +}); + +test("parseSessionIdentity reads alias fields from acpx metadata", () => { + assert.deepEqual( + parseSessionIdentity(JSON.stringify({ recordId: "record-123", sessionId: "session-456" })), + { + acpxRecordId: "record-123", + acpxSessionId: "session-456", + }, + ); + assert.deepEqual( + parseSessionIdentity(JSON.stringify({ acpxRecordId: "record-123", acpxSessionId: "session-456" })), + { + acpxRecordId: "record-123", + acpxSessionId: "session-456", + }, + ); +}); + +test("readSessionIdentityResult streams large acpx metadata through file capture", () => { + const dir = mkdtempSync(join(tmpdir(), "acpx-identity-test-")); + const oldPath = process.env.PATH; + try { + const acpxPath = join(dir, "acpx"); + writeFileSync( + acpxPath, + `#!/usr/bin/env node\nprocess.stdout.write(JSON.stringify({ acpxRecordId: "record-123", acpSessionId: "session-456", messages: "x".repeat(2 * 1024 * 1024) }));\n`, + "utf8", + ); + chmodSync(acpxPath, 0o755); + process.env.PATH = `${dir}${delimiter}${oldPath || ""}`; + + const result = readSessionIdentityResult("codex", "session-name", process.cwd()); + + assert.deepEqual(result, { + identity: { + acpxRecordId: "record-123", + acpxSessionId: "session-456", + }, + error: "", + }); + } finally { + if (oldPath === undefined) { + delete process.env.PATH; + } else { + process.env.PATH = oldPath; + } + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("parseSessionIdentity returns null for incomplete payloads", () => { + assert.equal(parseSessionIdentity(JSON.stringify({ acpxRecordId: "record-only" })), null); + assert.equal(parseSessionIdentity("unknown: data"), null); +}); + +test("sessionNameFromThreadKey drops the repo prefix and keeps route identity", () => { + assert.equal( + sessionNameFromThreadKey("self-evolving/repo:pull_request:38:fix-pr:default"), + "pull_request-38-fix-pr-default", + ); +}); diff --git a/.agent/src/__tests__/add-label-cli.test.ts b/.agent/src/__tests__/add-label-cli.test.ts new file mode 100644 index 0000000..9f39d88 --- /dev/null +++ b/.agent/src/__tests__/add-label-cli.test.ts @@ -0,0 +1,146 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): string { + const fakeGh = join(tempDir, "gh"); + writeFileSync(fakeGh, body, { encoding: "utf8", mode: 0o755 }); + return fakeGh; +} + +function runAddLabel(tempDir: string, env: Record) { + return spawnSync("node", [".agent/dist/cli/add-label.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + ...env, + }, + encoding: "utf8", + }); +} + +test("add-label CLI skips all gh calls unless AGENT_STATUS_LABEL_ENABLED is true", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-add-label-")); + + try { + const logPath = join(tempDir, "gh.log"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +exit 1 +`, + ); + + const result = runAddLabel(tempDir, { + AGENT_STATUS_LABEL_ENABLED: "", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "issue", + TARGET_NUMBER: "42", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /skipping status label/); + assert.equal(existsSync(logPath), false); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("add-label CLI creates the fixed label and applies it to issues", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-add-label-")); + + try { + const logPath = join(tempDir, "gh.log"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "label" ] && [ "$2" = "list" ]; then + exit 0 +fi +if [ "$1" = "label" ] && [ "$2" = "create" ]; then + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "edit" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = runAddLabel(tempDir, { + AGENT_STATUS_LABEL_ENABLED: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "issue", + TARGET_NUMBER: "42", + }); + + assert.equal(result.status, 0); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^label list --search agent --json name --jq \.\[\]\.name --repo self-evolving\/repo$/m); + assert.match( + log, + /^label create agent --color 0e8a16 --description Handled by the agent --repo self-evolving\/repo$/m, + ); + assert.match(log, /^issue edit 42 --add-label agent --repo self-evolving\/repo$/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("add-label CLI treats concurrent label creation as success before applying the label", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-add-label-")); + + try { + const logPath = join(tempDir, "gh.log"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "label" ] && [ "$2" = "list" ]; then + exit 0 +fi +if [ "$1" = "label" ] && [ "$2" = "create" ]; then + printf 'already exists\\n' >&2 + exit 1 +fi +if [ "$1" = "pull_request" ] && [ "$2" = "edit" ]; then + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "edit" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = runAddLabel(tempDir, { + AGENT_STATUS_LABEL_ENABLED: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "12", + }); + + assert.equal(result.status, 0); + const log = readFileSync(logPath, "utf8"); + assert.match( + log, + /^label create agent --color 0e8a16 --description Handled by the agent --repo self-evolving\/repo$/m, + ); + assert.match(log, /^pr edit 12 --add-label agent --repo self-evolving\/repo$/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/agent-action-expiration.test.ts b/.agent/src/__tests__/agent-action-expiration.test.ts new file mode 100644 index 0000000..44b94db --- /dev/null +++ b/.agent/src/__tests__/agent-action-expiration.test.ts @@ -0,0 +1,74 @@ +import { mkdtempSync, readFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; +import test from "node:test"; +import assert from "node:assert/strict"; + +const repoRoot = resolve(__dirname, "../../.."); +const scriptPath = join( + repoRoot, + ".github/actions/check-agent-action-expiration/check-expiration.sh", +); + +function runExpirationCheck(expiresAt: string): { + status: number | null; + stdout: string; + stderr: string; + outputs: Record; +} { + const dir = mkdtempSync(join(tmpdir(), "agent-action-expiration-")); + const outputPath = join(dir, "github-output.txt"); + const result = spawnSync("bash", [scriptPath], { + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + INPUT_EXPIRES_AT: expiresAt, + }, + encoding: "utf8", + }); + let outputs: Record = {}; + try { + outputs = Object.fromEntries( + readFileSync(outputPath, "utf8") + .trim() + .split("\n") + .filter(Boolean) + .map((line) => { + const index = line.indexOf("="); + return [line.slice(0, index), line.slice(index + 1)]; + }), + ); + } catch { + outputs = {}; + } + return { + status: result.status, + stdout: result.stdout, + stderr: result.stderr, + outputs, + }; +} + +test("check-agent-action-expiration marks future and past dates", () => { + const future = runExpirationCheck("2099-01-01"); + assert.equal(future.status, 0); + assert.equal(future.outputs.expired, "false"); + assert.equal(future.outputs.expires_at, "2099-01-01"); + assert.match(future.outputs.today, /^\d{4}-\d{2}-\d{2}$/); + + const past = runExpirationCheck("2000-01-01"); + assert.equal(past.status, 0); + assert.equal(past.outputs.expired, "true"); + assert.equal(past.outputs.expires_at, "2000-01-01"); +}); + +test("check-agent-action-expiration rejects invalid dates", () => { + const invalidFormat = runExpirationCheck("01-01-2099"); + assert.equal(invalidFormat.status, 2); + assert.match(invalidFormat.stderr, /YYYY-MM-DD/); + + const impossibleDate = runExpirationCheck("2026-02-30"); + assert.equal(impossibleDate.status, 2); + assert.match(impossibleDate.stderr, /day is invalid/); +}); diff --git a/.agent/src/__tests__/apply-project-management-labels-cli.test.ts b/.agent/src/__tests__/apply-project-management-labels-cli.test.ts new file mode 100644 index 0000000..227ced8 --- /dev/null +++ b/.agent/src/__tests__/apply-project-management-labels-cli.test.ts @@ -0,0 +1,264 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): void { + writeFileSync(join(tempDir, "gh"), body, { encoding: "utf8", mode: 0o755 }); +} + +function writePlan(tempDir: string): string { + const bodyFile = join(tempDir, "summary.md"); + writeFileSync( + bodyFile, + `## Project Management Summary + +\`\`\`json +{ + "label_changes": [ + { + "kind": "issue", + "number": 34, + "add": ["priority/p1", "effort/high", "bug"], + "remove": ["priority/p3", "effort/low", "external"] + }, + { + "kind": "pull_request", + "number": 39, + "add": ["priority/p3", "effort/low"], + "remove": ["priority/p2", "effort/high"] + }, + { + "kind": "discussion", + "number": 7, + "add": ["priority/p0"], + "remove": [] + } + ] +} +\`\`\` +`, + ); + return bodyFile; +} + +function runCli(tempDir: string, env: Record) { + return spawnSync("node", [".agent/dist/cli/apply-project-management-labels.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + ...env, + }, + encoding: "utf8", + }); +} + +test("apply project management labels skips gh calls in dry-run mode", () => { + const tempDir = mkdtempSync(join(tmpdir(), "apply-project-labels-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + writePlan(tempDir); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +exit 1 +`, + ); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DRY_RUN: "true", + AGENT_PROJECT_MANAGEMENT_APPLY_LABELS: "true", + BODY_FILE: join(tempDir, "summary.md"), + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Dry run is enabled/); + assert.equal(readFileSync(outputPath, "utf8").includes("labels_applied"), true); + assert.throws(() => readFileSync(logPath, "utf8")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("apply project management labels fails dry-run without a valid plan", () => { + const cases = [ + ["missing fenced json", "## Project Management Summary\n\nNo structured plan.\n"], + ["malformed fenced json", "## Project Management Summary\n\n```json\nnot-json\n```\n"], + ]; + + for (const [name, body] of cases) { + const tempDir = mkdtempSync(join(tmpdir(), "apply-project-labels-")); + + try { + const bodyFile = join(tempDir, "summary.md"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + writeFileSync(bodyFile, body); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +exit 1 +`, + ); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DRY_RUN: "true", + AGENT_PROJECT_MANAGEMENT_APPLY_LABELS: "true", + BODY_FILE: bodyFile, + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 1, name); + assert.match(result.stderr, /valid fenced JSON label_changes plan/); + assert.throws(() => readFileSync(logPath, "utf8")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + } +}); + +test("apply project management labels defaults to applying managed changes", () => { + const tempDir = mkdtempSync(join(tmpdir(), "apply-project-labels-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + writePlan(tempDir); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "label" ] && [ "$2" = "list" ]; then + exit 0 +fi +if [ "$1" = "label" ] && [ "$2" = "create" ]; then + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "edit" ]; then + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "edit" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DRY_RUN: "false", + BODY_FILE: join(tempDir, "summary.md"), + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Applied 8 managed priority\/effort label operation/); + + const log = readFileSync(logPath, "utf8"); + for (const label of [ + "priority/p0", + "priority/p1", + "priority/p2", + "priority/p3", + "effort/low", + "effort/medium", + "effort/high", + ]) { + assert.match(log, new RegExp(`^label create ${label} `, "m")); + } + assert.match(log, /^issue edit 34 --remove-label priority\/p3 --repo self-evolving\/repo$/m); + assert.match(log, /^issue edit 34 --remove-label effort\/low --repo self-evolving\/repo$/m); + assert.match(log, /^issue edit 34 --add-label priority\/p1 --repo self-evolving\/repo$/m); + assert.match(log, /^issue edit 34 --add-label effort\/high --repo self-evolving\/repo$/m); + assert.match(log, /^pr edit 39 --remove-label priority\/p2 --repo self-evolving\/repo$/m); + assert.match(log, /^pr edit 39 --remove-label effort\/high --repo self-evolving\/repo$/m); + assert.match(log, /^pr edit 39 --add-label priority\/p3 --repo self-evolving\/repo$/m); + assert.match(log, /^pr edit 39 --add-label effort\/low --repo self-evolving\/repo$/m); + assert.doesNotMatch(log, / bug| external|discussion/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("apply project management labels fails real label application without a valid plan", () => { + const cases = [ + ["missing fenced json", "## Project Management Summary\n\nNo structured plan.\n"], + ["malformed fenced json", "## Project Management Summary\n\n```json\nnot-json\n```\n"], + ]; + + for (const [name, body] of cases) { + const tempDir = mkdtempSync(join(tmpdir(), "apply-project-labels-")); + + try { + const bodyFile = join(tempDir, "summary.md"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + writeFileSync(bodyFile, body); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +exit 1 +`, + ); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DRY_RUN: "false", + AGENT_PROJECT_MANAGEMENT_APPLY_LABELS: "true", + BODY_FILE: bodyFile, + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 1, name); + assert.match(result.stderr, /valid fenced JSON label_changes plan/); + assert.throws(() => readFileSync(logPath, "utf8")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + } +}); + +test("apply project management labels allows an explicit empty plan", () => { + const tempDir = mkdtempSync(join(tmpdir(), "apply-project-labels-")); + + try { + const bodyFile = join(tempDir, "summary.md"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + writeFileSync(bodyFile, "## Project Management Summary\n\n```json\n{\"label_changes\":[]}\n```\n"); + writeFakeGh(tempDir, "#!/usr/bin/env bash\nprintf '%s\\n' \"$*\" >> \"$FAKE_GH_LOG\"\nexit 1\n"); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DRY_RUN: "false", + AGENT_PROJECT_MANAGEMENT_APPLY_LABELS: "true", + BODY_FILE: bodyFile, + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Applied 0 managed priority\/effort label operation/); + assert.throws(() => readFileSync(logPath, "utf8")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/approval.test.ts b/.agent/src/__tests__/approval.test.ts new file mode 100644 index 0000000..7b141b3 --- /dev/null +++ b/.agent/src/__tests__/approval.test.ts @@ -0,0 +1,226 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + buildApprovalRequestMarker, + findPendingRequestById, + parseApprovalRequestMarker, + parseApprovalCommand, + isApprovalRequestAlreadySatisfied, + markApprovalRequestSatisfied, + isApprovalCommand, + isAgentApprovalComment, + shouldCreateIssueFromApprovalRequest, +} from "../approval.js"; + +test("approval marker round-trips through build and parse", () => { + const data = { route: "implement", target_kind: "issue", target_number: 42 }; + const marker = buildApprovalRequestMarker(data); + const parsed = parseApprovalRequestMarker(marker); + assert.deepEqual(parsed, data); +}); + +test("approval marker round-trips with request_text", () => { + const data = { + route: "implement", + request_text: "please implement this feature", + target_kind: "issue", + target_number: 42, + }; + const marker = buildApprovalRequestMarker(data); + const parsed = parseApprovalRequestMarker(marker); + assert.equal(parsed?.request_text, "please implement this feature"); +}); + +test("approval marker hides raw request text that contains HTML comment terminators", () => { + const data = { + route: "implement", + request_text: "do this --> and keep -- dangerous sequences hidden", + target_kind: "issue", + target_number: 42, + }; + const marker = buildApprovalRequestMarker(data); + const parsed = parseApprovalRequestMarker(marker); + + assert.ok(marker.startsWith("/g)?.length, 1); + assert.equal( + parsed?.request_text, + "do this --> and keep -- dangerous sequences hidden", + ); +}); + +test("parseApprovalRequestMarker returns null for corrupted encoded markers", () => { + assert.equal( + parseApprovalRequestMarker(""), + null, + ); + assert.equal( + parseApprovalRequestMarker( + "", + ), + null, + ); +}); + +test("parseApprovalRequestMarker returns null for non-marker content", () => { + assert.equal(parseApprovalRequestMarker("just a regular comment"), null); + assert.equal(parseApprovalRequestMarker(""), null); + assert.equal( + parseApprovalRequestMarker( + '', + ), + null, + ); +}); + +test("isApprovalCommand accepts only explicit mention slash-approve commands with ids", () => { + assert.ok(isApprovalCommand("@sepo-agent /approve req-a1b2c3")); + assert.ok(!isApprovalCommand("/approve req-a1b2c3")); + assert.ok(!isApprovalCommand("@sepo-agent approve req-a1b2c3")); + assert.ok(!isApprovalCommand("Sure, @sepo-agent /approve this")); + assert.ok(!isApprovalCommand("@sepo-agent review")); + assert.ok(!isApprovalCommand("just a comment")); +}); + +test("parseApprovalCommand extracts the request id", () => { + assert.deepEqual(parseApprovalCommand("@sepo-agent /approve req-a1b2c3"), { + requestId: "req-a1b2c3", + }); + assert.equal(parseApprovalCommand("@sepo-agent approve req-a1b2c3"), null); + assert.equal(parseApprovalCommand("@sepo-agent /approve"), null); +}); + +test("approval commands accept a configured mention", () => { + const mention = "@custom/agent"; + assert.ok(isApprovalCommand("@custom/agent /approve req-a1b2c3", mention)); + assert.deepEqual(parseApprovalCommand("@custom/agent /approve req-a1b2c3", mention), { + requestId: "req-a1b2c3", + }); + assert.equal(isApprovalCommand("@sepo-agent /approve req-a1b2c3", mention), false); +}); + +test("approval commands ignore fenced code blocks and quotes", () => { + const body = [ + "Example:", + "", + "```text", + "@sepo-agent /approve req-a1b2c3", + "```", + "", + "> @sepo-agent /approve req-z9y8x7", + ].join("\n"); + + assert.equal(isApprovalCommand(body), false); + assert.equal(parseApprovalCommand(body), null); +}); + +test("isApprovalRequestAlreadySatisfied detects the marker", () => { + assert.ok(!isApprovalRequestAlreadySatisfied("pending request")); + assert.ok( + isApprovalRequestAlreadySatisfied("body\n\n"), + ); +}); + +test("findPendingRequestById skips approved requests and matches exact ids", () => { + const marker = buildApprovalRequestMarker({ route: "implement", request_id: "req-old" }); + const comments = [ + { + id: "1", + body: `Request.\n\n${marker}\n\n`, + created_at: "2026-01-01T00:00:00Z", + }, + { + id: "2", + body: `Another.\n\n${buildApprovalRequestMarker({ route: "review", request_id: "req-new" })}`, + created_at: "2026-01-02T00:00:00Z", + }, + ]; + const result = findPendingRequestById(comments, "req-new"); + assert.ok(result); + assert.equal(result!.comment.id, "2"); + assert.equal(result!.request.route, "review"); +}); + +test("findPendingRequestById returns null when all matching ids are satisfied", () => { + const marker = buildApprovalRequestMarker({ route: "implement", request_id: "req-a1b2c3" }); + const comments = [ + { + id: "1", + body: `${marker}\n\n`, + created_at: "2026-01-01T00:00:00Z", + }, + ]; + assert.equal(findPendingRequestById(comments, "req-a1b2c3"), null); +}); + +test("findPendingRequestById returns null for empty list", () => { + assert.equal(findPendingRequestById([], "req-a1b2c3"), null); +}); + +test("isAgentApprovalComment detects request and satisfied markers", () => { + const requestMarker = buildApprovalRequestMarker({ route: "implement", request_id: "req-a1b2c3" }); + assert.ok(isAgentApprovalComment(requestMarker)); + assert.ok(isAgentApprovalComment("body\n\n")); + assert.equal(isAgentApprovalComment("just a human approval reply"), false); +}); + +test("markApprovalRequestSatisfied renders table with full context", () => { + const body = markApprovalRequestSatisfied("original body", "alice", { + route: "implement", + workflow: "agent-implement.yml", + issueUrl: "https://github.com/org/repo/issues/42", + runUrl: "https://github.com/org/repo/actions/runs/123", + }); + assert.match(body, /@alice/); + assert.match(body, /implement/); + assert.match(body, /#42/); + assert.match(body, /approval run/); + assert.match(body, /sepo-agent-approved/); +}); + +test("markApprovalRequestSatisfied renders table without extra context", () => { + const body = markApprovalRequestSatisfied("body", "bob"); + assert.match(body, /@bob/); + assert.match(body, /\u2014/); // em dash for missing tracking + assert.match(body, /sepo-agent-approved/); +}); + +test("shouldCreateIssueFromApprovalRequest only for non-issue implementation-like routes", () => { + assert.ok( + shouldCreateIssueFromApprovalRequest({ + route: "implement", + target_kind: "discussion", + issue_title: "feat: add X", + }), + ); + assert.ok( + shouldCreateIssueFromApprovalRequest({ + route: "create-action", + target_kind: "discussion", + issue_title: "Create scheduled action", + }), + ); + assert.ok( + !shouldCreateIssueFromApprovalRequest({ + route: "implement", + target_kind: "issue", + issue_title: "feat: add X", + }), + ); + assert.ok( + !shouldCreateIssueFromApprovalRequest({ + route: "review", + target_kind: "pull_request", + issue_title: "", + }), + ); + assert.ok( + !shouldCreateIssueFromApprovalRequest({ + route: "implement", + target_kind: "discussion", + issue_title: "", + }), + ); +}); diff --git a/.agent/src/__tests__/capture-pr-head-cli.test.ts b/.agent/src/__tests__/capture-pr-head-cli.test.ts new file mode 100644 index 0000000..8502b4c --- /dev/null +++ b/.agent/src/__tests__/capture-pr-head-cli.test.ts @@ -0,0 +1,46 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): void { + writeFileSync(join(tempDir, "gh"), body, { encoding: "utf8", mode: 0o755 }); +} + +test("capture-pr-head CLI writes empty output when PR metadata lookup fails", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-capture-pr-head-")); + + try { + const outputPath = join(tempDir, "github-output.txt"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf 'metadata unavailable\\n' >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/capture-pr-head.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_NUMBER: "172", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stderr, /Reviewed head capture skipped:/); + assert.match(readFileSync(outputPath, "utf8"), /^head_sha< { + const ctx = extractEventContext("pull_request_review_comment", { + comment: { + id: 42, + body: "fix the bug", + html_url: "https://github.com/org/repo/pull/5#discussion_r42", + node_id: "PRRC_42", + user: { login: "alice" }, + }, + pull_request: { + number: 5, + html_url: "https://github.com/org/repo/pull/5", + }, + }); + assert.equal(ctx.sourceKind, "pull_request_review_comment"); + assert.equal(ctx.targetKind, "pull_request"); + assert.equal(ctx.targetNumber, "5"); + assert.equal(ctx.responseKind, "review_comment_reply"); + assert.equal(ctx.reviewCommentId, "42"); + assert.equal(ctx.reactionSubjectId, "PRRC_42"); +}); + +test("extractEventContext captures triggering PR issue comments", () => { + const ctx = extractEventContext("issue_comment", { + comment: { + id: 99, + body: "please review", + html_url: "https://github.com/org/repo/issues/3#issuecomment-99", + node_id: "IC_99", + }, + issue: { + number: 3, + html_url: "https://github.com/org/repo/issues/3", + pull_request: { url: "https://api.github.com/repos/org/repo/pulls/3" }, + }, + }); + assert.equal(ctx.targetKind, "pull_request"); + assert.equal(ctx.sourceKind, "issue_comment"); + assert.equal(ctx.sourceCommentId, "99"); +}); + +test("extractEventContext captures triggering PR reviews", () => { + const ctx = extractEventContext("pull_request_review", { + review: { + id: 77, + body: "looks good", + html_url: "https://github.com/org/repo/pull/5#pullrequestreview-77", + node_id: "PRR_77", + user: { login: "bob" }, + }, + pull_request: { + number: 5, + html_url: "https://github.com/org/repo/pull/5", + }, + }); + assert.equal(ctx.sourceKind, "pull_request_review"); + assert.equal(ctx.targetKind, "pull_request"); + assert.equal(ctx.reactionSubjectId, "PRR_77"); +}); + +test("extractEventContext maps discussion comments to discussion replies", () => { + const ctx = extractEventContext("discussion_comment", { + comment: { + body: "interesting point", + node_id: "DC_10", + }, + discussion: { + number: 1, + html_url: "https://github.com/org/repo/discussions/1", + node_id: "D_1", + }, + }); + assert.equal(ctx.targetKind, "discussion"); + assert.equal(ctx.responseKind, "discussion_comment"); + assert.equal(ctx.discussionNodeId, "D_1"); + assert.equal(ctx.discussionCommentNodeId, "DC_10"); +}); + +test("extractEventContext extracts discussionNodeId for discussion body mentions", () => { + const ctx = extractEventContext("discussion", { + discussion: { + title: "Design", + body: "content", + number: 1, + html_url: "https://github.com/org/repo/discussions/1", + node_id: "D_1", + }, + }); + assert.equal(ctx.targetKind, "discussion"); + assert.equal(ctx.discussionNodeId, "D_1"); + assert.ok(ctx.body.includes("Design")); +}); + +test("getAuthorAssociation reads discussion associations", () => { + assert.equal( + getAuthorAssociation("discussion", { + discussion: { authorAssociation: "MEMBER" }, + }), + "MEMBER", + ); + assert.equal( + getAuthorAssociation("discussion_comment", { + comment: { author_association: "COLLABORATOR" }, + }), + "COLLABORATOR", + ); +}); + +test("getRequestedBy extracts login from various event types", () => { + assert.equal( + getRequestedBy("issue_comment", { comment: { user: { login: "alice" } } }), + "alice", + ); + assert.equal( + getRequestedBy("pull_request_review", { review: { user: { login: "bob" } } }), + "bob", + ); + assert.equal( + getRequestedBy("discussion", { discussion: { user: { login: "carol" } } }), + "carol", + ); +}); + +test("extractEventContext handles pull_request_target same as pull_request", () => { + const payload = { + pull_request: { + number: 7, + title: "feat: label triggers", + body: "Add label-based activation", + html_url: "https://github.com/org/repo/pull/7", + node_id: "PR_7", + author_association: "MEMBER", + user: { login: "alice" }, + }, + }; + const ctx = extractEventContext("pull_request_target", payload); + assert.equal(ctx.sourceKind, "pull_request"); + assert.equal(ctx.targetKind, "pull_request"); + assert.equal(ctx.targetNumber, "7"); + assert.equal(ctx.reactionSubjectId, "PR_7"); + assert.ok(ctx.body.includes("label triggers")); + + assert.equal(getAuthorAssociation("pull_request_target", payload), "MEMBER"); + assert.equal(getRequestedBy("pull_request_target", payload), "alice"); +}); + +test("shouldRespondToMention only triggers when an issue edit adds a mention", () => { + assert.equal( + shouldRespondToMention( + "issues", + { + action: "edited", + issue: { + title: "Need @sepo-agent", + body: "body", + }, + changes: { + title: { + from: "Need help", + }, + }, + }, + "@sepo-agent", + ), + true, + ); + + assert.equal( + shouldRespondToMention( + "issues", + { + action: "edited", + issue: { + title: "Need @sepo-agent", + body: "updated body", + }, + changes: { + body: { + from: "body", + }, + }, + }, + "@sepo-agent", + ), + false, + ); +}); + +test("shouldRespondToMention only triggers when an edited comment adds a mention", () => { + assert.equal( + shouldRespondToMention( + "issue_comment", + { + action: "edited", + comment: { + body: "please check @sepo-agent", + }, + changes: { + body: { + from: "please check", + }, + }, + }, + "@sepo-agent", + ), + true, + ); + + assert.equal( + shouldRespondToMention( + "issue_comment", + { + action: "edited", + comment: { + body: "please check @sepo-agent again", + }, + changes: { + body: { + from: "please check @sepo-agent", + }, + }, + }, + "@sepo-agent", + ), + false, + ); + + assert.equal( + shouldRespondToMention( + "pull_request_review_comment", + { + action: "edited", + comment: { + body: "please check @sepo-agent", + }, + changes: { + body: { + from: "please check", + }, + }, + }, + "@sepo-agent", + ), + true, + ); +}); + +test("shouldSkipSender filters bots", () => { + assert.ok(shouldSkipSender({ sender: { type: "Bot", login: "dependabot[bot]" } })); + assert.ok(shouldSkipSender({ sender: { type: "User", login: "github-actions" } })); + assert.ok(!shouldSkipSender({ sender: { type: "User", login: "alice" } })); +}); diff --git a/.agent/src/__tests__/discussion-post-gate-shell.test.ts b/.agent/src/__tests__/discussion-post-gate-shell.test.ts new file mode 100644 index 0000000..8a03e1c --- /dev/null +++ b/.agent/src/__tests__/discussion-post-gate-shell.test.ts @@ -0,0 +1,132 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +function writeFakeGh(tempDir: string, responses: string | string[]): void { + const responseList = Array.isArray(responses) ? responses : [responses]; + responseList.forEach((response, index) => { + writeFileSync(join(tempDir, `response-${index}.json`), response); + }); + + writeFileSync( + join(tempDir, "gh"), + `#!/usr/bin/env bash +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + count_file="${join(tempDir, "gh-count")}" + count="$(cat "$count_file" 2>/dev/null || printf '0')" + response_file="${join(tempDir, "response-")}$count.json" + next_count="$((count + 1))" + printf '%s' "$next_count" > "$count_file" + if [ -f "$response_file" ]; then + cat "$response_file" + exit 0 + fi + printf 'missing fake gh response: %s\\n' "$response_file" >&2 + exit 1 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); +} + +function runGate(tempDir: string, env: Record) { + const outputFile = join(tempDir, "outputs.txt"); + const result = spawnSync("bash", ["scripts/resolve-discussion-post-gate.sh"], { + cwd: process.cwd(), + env: { + ...process.env, + GITHUB_OUTPUT: outputFile, + GITHUB_REPOSITORY: "self-evolving/repo", + PATH: `${tempDir}:${process.env.PATH || ""}`, + ...env, + }, + encoding: "utf8", + }); + const outputText = result.status === 0 ? readFileSync(outputFile, "utf8") : ""; + const payload = result.stdout.trim() ? JSON.parse(result.stdout) : null; + return { result, outputText, payload }; +} + +test("discussion post gate skips when repository discussions are disabled", () => { + const tempDir = mkdtempSync(join(tmpdir(), "discussion-gate-")); + try { + writeFakeGh(tempDir, '{"data":{"repository":{"hasDiscussionsEnabled":false,"discussionCategories":{"nodes":[]}}}}'); + + const { result, outputText, payload } = runGate(tempDir, { + DISCUSSION_CATEGORY: "General", + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, true); + assert.equal(payload.reason, "repository discussions are disabled"); + assert.match(outputText, /skip<<[\s\S]*true/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("discussion post gate skips when the configured category is missing", () => { + const tempDir = mkdtempSync(join(tmpdir(), "discussion-gate-")); + try { + writeFakeGh( + tempDir, + '{"data":{"repository":{"hasDiscussionsEnabled":true,"discussionCategories":{"nodes":[{"name":"General"}]}}}}', + ); + + const { result, payload } = runGate(tempDir, { + DISCUSSION_CATEGORY: "Daily Summaries", + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, true); + assert.equal(payload.reason, "discussion category 'Daily Summaries' was not found"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("discussion post gate allows summary generation when posting is available", () => { + const tempDir = mkdtempSync(join(tmpdir(), "discussion-gate-")); + try { + writeFakeGh( + tempDir, + '{"data":{"repository":{"hasDiscussionsEnabled":true,"discussionCategories":{"nodes":[{"name":"General"}]}}}}', + ); + + const { result, payload } = runGate(tempDir, { + DISCUSSION_CATEGORY: "General", + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, false); + assert.equal(payload.reason, "discussion posting is available"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("discussion post gate paginates categories before deciding posting is available", () => { + const tempDir = mkdtempSync(join(tmpdir(), "discussion-gate-")); + try { + writeFakeGh(tempDir, [ + '{"data":{"repository":{"hasDiscussionsEnabled":true,"discussionCategories":{"nodes":[{"name":"General"}],"pageInfo":{"hasNextPage":true,"endCursor":"cursor-1"}}}}}', + '{"data":{"repository":{"hasDiscussionsEnabled":true,"discussionCategories":{"nodes":[{"name":"Daily Summaries"}],"pageInfo":{"hasNextPage":false,"endCursor":"cursor-2"}}}}}', + ]); + + const { result, payload } = runGate(tempDir, { + DISCUSSION_CATEGORY: "Daily Summaries", + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(readFileSync(join(tempDir, "gh-count"), "utf8"), "2"); + assert.equal(payload.skip, false); + assert.equal(payload.reason, "discussion posting is available"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/discussion-transcript.test.ts b/.agent/src/__tests__/discussion-transcript.test.ts new file mode 100644 index 0000000..2683442 --- /dev/null +++ b/.agent/src/__tests__/discussion-transcript.test.ts @@ -0,0 +1,236 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + buildDiscussionTranscript, + fetchDiscussionTranscript, + formatDiscussionTranscriptComment, +} from "../discussion-transcript.js"; +import type { GraphQLClient, GraphQLVariableValue } from "../github-graphql.js"; + +function createQueuedClient(responses: unknown[]): { + client: GraphQLClient; + calls: Array<{ query: string; variables: Record }>; +} { + const calls: Array<{ query: string; variables: Record }> = []; + + const client: GraphQLClient = { + graphql( + query: string, + variables: Record, + ): T { + calls.push({ query, variables: { ...variables } }); + if (responses.length === 0) { + throw new Error("Unexpected GraphQL call"); + } + return responses.shift() as T; + }, + }; + + return { client, calls }; +} + +test("buildDiscussionTranscript includes discussion metadata and nested replies", () => { + const transcript = buildDiscussionTranscript( + { + id: "discussion-1", + title: "Discussion title", + url: "https://github.com/self-evolving/repo/discussions/1", + author: "alice", + body: "Discussion body", + }, + [ + { + id: "comment-1", + author: "bob", + createdAt: "2026-03-30T00:00:00Z", + body: "Top-level comment", + replyToId: "", + replies: [ + { + id: "reply-1", + author: "carol", + createdAt: "2026-03-30T01:00:00Z", + body: "Thread reply", + replyToId: "comment-1", + }, + ], + }, + ], + ); + + assert.match(transcript, /Title: Discussion title/); + assert.match(transcript, /### Comment by bob/); + assert.match(transcript, /#### Reply by carol/); + assert.match(transcript, /Thread reply/); +}); + +test("buildDiscussionTranscript renders an empty comment section explicitly", () => { + const transcript = buildDiscussionTranscript( + { + id: "discussion-2", + title: "No comments yet", + url: "https://github.com/self-evolving/repo/discussions/2", + author: "alice", + body: "Discussion body", + }, + [], + ); + + assert.match(transcript, /## Comments/); + assert.match(transcript, /_No comments yet\._/); +}); + +test("formatDiscussionTranscriptComment uses ghost fallback and reply headings", () => { + const formatted = formatDiscussionTranscriptComment( + { + id: "reply-1", + body: "Nested reply", + createdAt: "", + author: "", + replyToId: "comment-1", + }, + 1, + ); + + assert.match(formatted, /#### Reply by ghost at /); + assert.match(formatted, /Nested reply/); +}); + +test("fetchDiscussionTranscript paginates top-level comments and reply threads", async () => { + const { client, calls } = createQueuedClient([ + { + repository: { + discussion: { + id: "discussion-1", + title: "Discussion title", + url: "https://github.com/self-evolving/repo/discussions/1", + body: "Discussion body", + author: { login: "alice" }, + comments: { + nodes: [ + { + id: "comment-1", + body: "First comment", + createdAt: "2026-03-30T00:00:00Z", + author: { login: "bob" }, + replyTo: null, + replies: { + nodes: [ + { + id: "reply-1", + body: "First reply", + createdAt: "2026-03-30T00:05:00Z", + author: { login: "carol" }, + replyTo: { id: "comment-1" }, + }, + ], + pageInfo: { + hasNextPage: true, + endCursor: "reply-cursor-1", + }, + }, + }, + ], + pageInfo: { + hasNextPage: true, + endCursor: "comment-cursor-1", + }, + }, + }, + }, + }, + { + node: { + replies: { + nodes: [ + { + id: "reply-2", + body: "Second reply", + createdAt: "2026-03-30T00:10:00Z", + author: { login: "dave" }, + replyTo: { id: "comment-1" }, + }, + ], + pageInfo: { + hasNextPage: false, + endCursor: null, + }, + }, + }, + }, + { + repository: { + discussion: { + id: "discussion-1", + title: "Discussion title", + url: "https://github.com/self-evolving/repo/discussions/1", + body: "Discussion body", + author: { login: "alice" }, + comments: { + nodes: [ + { + id: "comment-2", + body: "Second comment", + createdAt: "2026-03-30T01:00:00Z", + author: { login: "erin" }, + replyTo: null, + replies: { + nodes: [], + pageInfo: { + hasNextPage: false, + endCursor: null, + }, + }, + }, + ], + pageInfo: { + hasNextPage: false, + endCursor: null, + }, + }, + }, + }, + }, + ]); + + const result = await fetchDiscussionTranscript( + client, + "self-evolving", + "repo", + 1, + ); + + assert.equal(result.discussionMeta.id, "discussion-1"); + assert.equal(result.comments.length, 2); + assert.equal(result.comments[0].id, "comment-1"); + assert.equal(result.comments[0].replies.length, 2); + assert.equal(result.comments[0].replies[1].id, "reply-2"); + assert.equal(result.comments[1].id, "comment-2"); + + assert.equal(calls.length, 3); + assert.equal(calls[0].variables.number, 1); + assert.equal(calls[0].variables.after, undefined); + assert.equal(calls[1].variables.commentId, "comment-1"); + assert.equal(calls[1].variables.after, "reply-cursor-1"); + assert.equal(calls[2].variables.after, "comment-cursor-1"); +}); + +test("fetchDiscussionTranscript throws when the discussion cannot be found", () => { + const { client } = createQueuedClient([ + { + repository: { + discussion: null, + }, + }, + ]); + + let message = ""; + try { + fetchDiscussionTranscript(client, "self-evolving", "repo", 404); + } catch (error: unknown) { + message = error instanceof Error ? error.message : String(error); + } + + assert.equal(message, "Discussion #404 not found"); +}); diff --git a/.agent/src/__tests__/discussion.test.ts b/.agent/src/__tests__/discussion.test.ts new file mode 100644 index 0000000..cb164cb --- /dev/null +++ b/.agent/src/__tests__/discussion.test.ts @@ -0,0 +1,122 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + createDiscussion, + createRepositoryDiscussion, + fetchRepositoryDiscussionConfig, + requireDiscussionCategory, +} from "../discussion.js"; +import type { GraphQLClient, GraphQLVariableValue } from "../github-graphql.js"; + +function queuedClient(responses: unknown[]): { + client: GraphQLClient; + calls: Array<{ query: string; variables: Record }>; +} { + const calls: Array<{ query: string; variables: Record }> = []; + const client: GraphQLClient = { + graphql(query: string, variables: Record): T { + calls.push({ query, variables: { ...variables } }); + if (responses.length === 0) throw new Error("Unexpected GraphQL call"); + return responses.shift() as T; + }, + }; + return { client, calls }; +} + +test("fetchRepositoryDiscussionConfig paginates categories", () => { + const { client, calls } = queuedClient([ + { + repository: { + id: "repo-1", + hasDiscussionsEnabled: true, + discussionCategories: { + nodes: [{ id: "cat-1", name: "General" }], + pageInfo: { hasNextPage: true, endCursor: "cursor-1" }, + }, + }, + }, + { + repository: { + id: "repo-1", + hasDiscussionsEnabled: true, + discussionCategories: { + nodes: [{ id: "cat-2", name: "Daily Summaries" }], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + ]); + + const config = fetchRepositoryDiscussionConfig(client, "self-evolving", "repo"); + + assert.equal(config.repositoryId, "repo-1"); + assert.equal(config.hasDiscussionsEnabled, true); + assert.deepEqual(config.categories, [ + { id: "cat-1", name: "General" }, + { id: "cat-2", name: "Daily Summaries" }, + ]); + assert.equal(calls.length, 2); + assert.equal(calls[0]?.variables.cursor, undefined); + assert.equal(calls[1]?.variables.cursor, "cursor-1"); +}); + +test("requireDiscussionCategory validates discussion configuration", () => { + assert.throws( + () => requireDiscussionCategory({ + repositoryId: "repo-1", + hasDiscussionsEnabled: false, + categories: [], + }, "Daily Summaries"), + /discussions are not enabled/, + ); + + assert.throws( + () => requireDiscussionCategory({ + repositoryId: "repo-1", + hasDiscussionsEnabled: true, + categories: [{ id: "cat-1", name: "General" }], + }, "Daily Summaries"), + /Required discussion category 'Daily Summaries' was not found/, + ); +}); + +test("createDiscussion returns the created discussion URL", () => { + const { client, calls } = queuedClient([ + { createDiscussion: { discussion: { url: "https://github.com/org/repo/discussions/1" } } }, + ]); + + const discussion = createDiscussion(client, "repo-1", "cat-1", "Daily Summary", "Body"); + + assert.equal(discussion.url, "https://github.com/org/repo/discussions/1"); + assert.equal(calls.length, 1); + assert.match(calls[0]?.query || "", /createDiscussion/); +}); + +test("createRepositoryDiscussion composes config lookup and creation", () => { + const { client, calls } = queuedClient([ + { + repository: { + id: "repo-1", + hasDiscussionsEnabled: true, + discussionCategories: { + nodes: [{ id: "cat-1", name: "Daily Summaries" }], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + { createDiscussion: { discussion: { url: "https://github.com/org/repo/discussions/2" } } }, + ]); + + const discussion = createRepositoryDiscussion( + "org", + "repo", + "Daily Summaries", + "Daily Summary", + "Body", + client, + ); + + assert.equal(discussion.url, "https://github.com/org/repo/discussions/2"); + assert.equal(calls.length, 2); +}); diff --git a/.agent/src/__tests__/dispatch-agent-implement-cli.test.ts b/.agent/src/__tests__/dispatch-agent-implement-cli.test.ts new file mode 100644 index 0000000..8b162d3 --- /dev/null +++ b/.agent/src/__tests__/dispatch-agent-implement-cli.test.ts @@ -0,0 +1,49 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +test("dispatch-agent-implement forwards stacked PR base inputs", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-dispatch-implement-")); + try { + const payloadPath = join(tempDir, "dispatch.json"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +set -euo pipefail +if [ "\${1-}" = "api" ] && [ "\${2-}" = "-X" ] && [ "\${3-}" = "POST" ]; then + cat > "$FAKE_DISPATCH_PAYLOAD" + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = spawnSync("node", [".agent/dist/cli/dispatch-agent-implement.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + FAKE_DISPATCH_PAYLOAD: payloadPath, + GITHUB_REPOSITORY: "self-evolving/repo", + DEFAULT_BRANCH: "main", + ISSUE_NUMBER: "30", + REQUESTED_BY: "lolipopshock", + BASE_BRANCH: "agent/parent-branch", + BASE_PR: "", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.ok(existsSync(payloadPath)); + const payload = JSON.parse(readFileSync(payloadPath, "utf8")); + assert.equal(payload.inputs.base_branch, "agent/parent-branch"); + assert.equal(payload.inputs.base_pr, ""); + assert.equal(payload.inputs.automation_max_rounds, "12"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/dispatch-agent-orchestrator-cli.test.ts b/.agent/src/__tests__/dispatch-agent-orchestrator-cli.test.ts new file mode 100644 index 0000000..07c6200 --- /dev/null +++ b/.agent/src/__tests__/dispatch-agent-orchestrator-cli.test.ts @@ -0,0 +1,112 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +test("dispatch-agent-orchestrator defaults automation max rounds to 12", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-dispatch-orchestrator-")); + try { + const payloadPath = join(tempDir, "dispatch.json"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +set -euo pipefail +if [ "\${1-}" = "api" ] && [ "\${2-}" = "-X" ] && [ "\${3-}" = "POST" ]; then + cat > "$FAKE_DISPATCH_PAYLOAD" + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = spawnSync("node", [".agent/dist/cli/dispatch-agent-orchestrator.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + FAKE_DISPATCH_PAYLOAD: payloadPath, + GITHUB_REPOSITORY: "self-evolving/repo", + DEFAULT_BRANCH: "main", + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "requested", + TARGET_KIND: "issue", + TARGET_NUMBER: "30", + REQUESTED_BY: "lolipopshock", + REQUEST_TEXT: "@sepo-agent /orchestrate", + AUTOMATION_MODE: "agent", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0, result.stderr || result.stdout); + assert.ok(existsSync(payloadPath)); + const payload = JSON.parse(readFileSync(payloadPath, "utf8")); + assert.equal(payload.inputs.automation_max_rounds, "12"); + assert.equal(payload.inputs.automation_current_round, "1"); + assert.equal(payload.inputs.source_action, "orchestrate"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("dispatch-agent-orchestrator forwards review recommended next step", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-dispatch-orchestrator-")); + try { + const payloadPath = join(tempDir, "dispatch.json"); + const responsePath = join(tempDir, "response.md"); + writeFileSync( + responsePath, + [ + "## Recommended Next Step", + "HUMAN_DECISION: Let self-approval decide whether the warnings are acceptable.", + "", + "## Final Verdict", + "MINOR_ISSUES", + "", + "## Action Items", + "- [ ] Optional polish that should not become fix-pr context.", + ].join("\n"), + "utf8", + ); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +set -euo pipefail +if [ "\${1-}" = "api" ] && [ "\${2-}" = "-X" ] && [ "\${3-}" = "POST" ]; then + cat > "$FAKE_DISPATCH_PAYLOAD" + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = spawnSync("node", [".agent/dist/cli/dispatch-agent-orchestrator.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + FAKE_DISPATCH_PAYLOAD: payloadPath, + GITHUB_REPOSITORY: "self-evolving/repo", + DEFAULT_BRANCH: "main", + SOURCE_ACTION: "review", + RESPONSE_FILE: responsePath, + TARGET_KIND: "pull_request", + TARGET_NUMBER: "30", + REQUESTED_BY: "lolipopshock", + REQUEST_TEXT: "@sepo-agent /orchestrate", + AUTOMATION_MODE: "heuristics", + ORCHESTRATION_ENABLED: "true", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0, result.stderr || result.stdout); + assert.ok(existsSync(payloadPath)); + const payload = JSON.parse(readFileSync(payloadPath, "utf8")); + assert.equal(payload.inputs.source_conclusion, "minor_issues"); + assert.equal(payload.inputs.source_recommended_next_step, "human_decision"); + assert.equal(payload.inputs.source_handoff_context, ""); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/envelope.test.ts b/.agent/src/__tests__/envelope.test.ts new file mode 100644 index 0000000..0a767c7 --- /dev/null +++ b/.agent/src/__tests__/envelope.test.ts @@ -0,0 +1,1797 @@ +import { readFileSync, readdirSync } from "node:fs"; +import path from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { parse as parseYaml } from "yaml"; + +import { + buildEnvelope, + buildEnvelopeFromEventContext, + buildThreadKey, + envelopeToPromptVars, + SCHEMA_VERSION, + validateEnvelope, +} from "../envelope.js"; + +const repoRoot = path.resolve(__dirname, "../../.."); + +function readRepoFile(relativePath: string): string { + return readFileSync(path.join(repoRoot, relativePath), "utf8"); +} + +function readSupplementalPromptVarNames(runSource: string): Set { + const match = runSource.match(/const SUPPLEMENTAL_PROMPT_VAR_NAMES = \[([\s\S]*?)\] as const;/); + assert.ok(match, "run.ts should define SUPPLEMENTAL_PROMPT_VAR_NAMES"); + return new Set(Array.from(match[1].matchAll(/"([^"]+)"/g), ([, name]) => name)); +} + +function isRecord(value: unknown): value is Record { + return !!value && typeof value === "object" && !Array.isArray(value); +} + +function readBranchCleanupScript(): string { + const workflow = parseYaml(readRepoFile(".github/workflows/agent-branch-cleanup.yml")) as unknown; + assert.ok(isRecord(workflow), "branch cleanup workflow should parse as a YAML object"); + assert.ok(isRecord(workflow.jobs), "branch cleanup workflow should define jobs"); + const cleanupJob = workflow.jobs.cleanup; + assert.ok(isRecord(cleanupJob), "branch cleanup workflow should define cleanup job"); + assert.ok(Array.isArray(cleanupJob.steps), "branch cleanup job should define steps"); + + const githubScriptStep = cleanupJob.steps.find( + (step): step is Record => + isRecord(step) && step.uses === "actions/github-script@v7", + ); + assert.ok(githubScriptStep, "branch cleanup workflow should use actions/github-script"); + assert.ok(isRecord(githubScriptStep.with), "github-script step should define inputs"); + const script = githubScriptStep.with.script; + if (typeof script !== "string") { + assert.fail("github-script step should define a script input"); + } + + return script; +} + +async function runBranchCleanupScript(args: { + github: unknown; + context: unknown; + core: unknown; +}): Promise { + const script = readBranchCleanupScript(); + const run = new Function( + "github", + "context", + "core", + `"use strict"; return (async () => {\n${script}\n})();`, + ) as (github: unknown, context: unknown, core: unknown) => Promise; + + await run(args.github, args.context, args.core); +} + +const VALID_PARAMS = { + repo_slug: "self-evolving/repo", + route: "review", + source_kind: "issue_comment", + target_kind: "pull_request", + target_number: 42, + target_url: "https://github.com/self-evolving/repo/pull/42", + request_text: "please review this", + requested_by: "lolipopshock", +}; + +test("shared base prompt exists and contains the metadata contract", () => { + const base = readRepoFile(".github/prompts/_base.md"); + + assert.match(base, /Target: \$\{TARGET_KIND\} #\$\{TARGET_NUMBER\}/); + assert.match(base, /Source: \$\{SOURCE_KIND\}/); + assert.match(base, /URL: \$\{TARGET_URL\}/); + assert.match(base, /\$\{REPO_SLUG\}/); + assert.match(base, /\$\{REQUESTED_BY\}/); + assert.match(base, /\$\{REQUEST_TEXT\}/); + assert.match(base, /gh issue view/); + assert.match(base, /gh pr view/); +}); + +test("route prompts do not duplicate the base metadata header", () => { + const reviewPrompt = readRepoFile(".github/prompts/review.md"); + const implementPrompt = readRepoFile(".github/prompts/agent-implement.md"); + + assert.doesNotMatch(reviewPrompt, /Target: \$\{TARGET_KIND\} #\$\{TARGET_NUMBER\}/); + assert.doesNotMatch(implementPrompt, /Target: \$\{TARGET_KIND\} #\$\{TARGET_NUMBER\}/); + assert.doesNotMatch(reviewPrompt, /Source: \$\{SOURCE_KIND\}/); + assert.doesNotMatch(implementPrompt, /Source: \$\{SOURCE_KIND\}/); +}); + +test("review and implement prompts use self-serve context gathering", () => { + const reviewPrompt = readRepoFile(".github/prompts/review.md"); + const implementPrompt = readRepoFile(".github/prompts/agent-implement.md"); + + assert.match(reviewPrompt, /gh pr view \$\{TARGET_NUMBER\} --repo \$\{REPO_SLUG\}/); + assert.match(reviewPrompt, /gh pr diff \$\{TARGET_NUMBER\} --repo \$\{REPO_SLUG\}/); + assert.doesNotMatch( + reviewPrompt, + /\$\{PR_META_FILE\}|\$\{DIFF_FILE\}|\$\{RESOURCE_MANIFEST_FILE\}/, + ); + + assert.match(implementPrompt, /gh issue view \$\{TARGET_NUMBER\} --repo \$\{REPO_SLUG\}/); + assert.match(implementPrompt, /"commit_message"/); + assert.match(implementPrompt, /Closes #\$\{TARGET_NUMBER\}/); + assert.doesNotMatch( + implementPrompt, + /\$\{PRIMARY_CONTEXT_FILE\}|\$\{RESOURCE_MANIFEST_FILE\}/, + ); +}); + +test("issue enhancement prompt uses self-serve context gathering", () => { + const issueEnhancePrompt = readRepoFile(".github/prompts/agent-issue-enhance.md"); + + assert.match(issueEnhancePrompt, /gh issue view \$\{TARGET_NUMBER\} --repo \$\{REPO_SLUG\}/); + assert.doesNotMatch(issueEnhancePrompt, /\$\{PRIMARY_CONTEXT_FILE\}|\$\{RESOURCE_MANIFEST_FILE\}/); +}); + +test("answer prompt returns content for workflow posting instead of commenting directly", () => { + const answerPrompt = readRepoFile(".github/prompts/agent-answer.md"); + + assert.match(answerPrompt, /do not post comments directly via `gh`/i); + assert.match(answerPrompt, /workflow will post it on the original surface/i); +}); + +test("fix-pr prompt uses self-serve context, not local snapshots", () => { + const fixPrompt = readRepoFile(".github/prompts/agent-fix-pr.md"); + + assert.doesNotMatch(fixPrompt, /\$\{PR_META_FILE\}/); + assert.doesNotMatch(fixPrompt, /\$\{PR_DIFF_FILE\}/); + assert.doesNotMatch(fixPrompt, /\$\{REVIEW_COMMENTS_FILE\}/); + assert.doesNotMatch(fixPrompt, /\$\{REQUEST_COMMENT_FILE\}/); + assert.doesNotMatch(fixPrompt, /\$\{RESOURCE_MANIFEST_FILE\}/); + assert.match(fixPrompt, /gh pr view \$\{TARGET_NUMBER\}/); + assert.match(fixPrompt, /\$\{REQUEST_COMMENT_ID\}/); + assert.match(fixPrompt, /"commit_message"/); +}); + +test("agent-review and agent-implement workflows do not build linked context", () => { + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + + assert.doesNotMatch(reviewWorkflow, /build-linked-context\.cjs/); + assert.doesNotMatch(implementWorkflow, /build-linked-context\.cjs/); +}); + +test("all execution workflows use the shared run-agent-task action", () => { + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const selfApprovalWorkflow = readRepoFile(".github/workflows/agent-self-approve.yml"); + + for (const workflow of [implementWorkflow, reviewWorkflow, fixPrWorkflow, selfApprovalWorkflow]) { + assert.match(workflow, /uses: \.\/\.github\/actions\/run-agent-task/); + assert.doesNotMatch(workflow, /\.github\/scripts\/lib\/agent\/run-codex\.sh/); + } + + assert.doesNotMatch(fixPrWorkflow, /build-linked-context\.cjs/); +}); + +test("run-agent-task workflow steps are guarded by resolved task timeouts", () => { + const workflowPaths = readdirSync(path.join(repoRoot, ".github/workflows")) + .filter((file) => file.endsWith(".yml")) + .map((file) => `.github/workflows/${file}`) + .concat(".agent/action-templates/agent-action-template.yml"); + let guardedSteps = 0; + + for (const workflowPath of workflowPaths) { + const workflow = parseYaml(readRepoFile(workflowPath)) as unknown; + assert.ok(isRecord(workflow), `${workflowPath} should parse as a YAML object`); + const jobs = workflow.jobs; + if (!isRecord(jobs)) continue; + + for (const [jobId, job] of Object.entries(jobs)) { + if (!isRecord(job) || !Array.isArray(job.steps)) continue; + + const resolverStepIds = new Set(); + for (const step of job.steps) { + if (!isRecord(step)) continue; + if (String(step.run || "").includes("node .agent/dist/cli/resolve-task-timeout.js")) { + const id = String(step.id || ""); + assert.ok(id, `${workflowPath} job ${jobId} timeout resolver needs an id`); + assert.ok(isRecord(step.env), `${workflowPath} job ${jobId} timeout resolver needs env`); + assert.equal( + step.env.AGENT_TASK_TIMEOUT_POLICY, + "${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }}", + `${workflowPath} job ${jobId} timeout resolver should read AGENT_TASK_TIMEOUT_POLICY`, + ); + assert.ok(step.env.ROUTE, `${workflowPath} job ${jobId} timeout resolver needs ROUTE`); + resolverStepIds.add(id); + } + + if (step.uses === "./.github/actions/run-agent-task") { + const timeout = String(step["timeout-minutes"] || ""); + const match = timeout.match(/steps\.([a-zA-Z0-9_-]+)\.outputs\.minutes/); + assert.ok(match, `${workflowPath} job ${jobId} run-agent-task step needs timeout-minutes from resolver output`); + assert.ok( + resolverStepIds.has(match[1]!), + `${workflowPath} job ${jobId} timeout resolver must precede run-agent-task`, + ); + assert.equal( + timeout, + "${{ fromJson(steps.task_timeout.outputs.minutes || '30') }}", + `${workflowPath} job ${jobId} should coerce resolved timeout minutes`, + ); + guardedSteps += 1; + } + } + } + } + + assert.ok(guardedSteps > 0); +}); + +test("single-agent workflows resolve provider before runtime setup", () => { + const routerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const updateWorkflow = readRepoFile(".github/workflows/agent-update.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const selfApprovalWorkflow = readRepoFile(".github/workflows/agent-self-approve.yml"); + const autonomousWorkflows = [ + updateWorkflow, + readRepoFile(".github/workflows/agent-daily-summary.yml"), + readRepoFile(".github/workflows/agent-memory-bootstrap.yml"), + readRepoFile(".github/workflows/agent-memory-pr-closed.yml"), + readRepoFile(".github/workflows/agent-memory-scan.yml"), + readRepoFile(".github/workflows/agent-rubrics-initialization.yml"), + readRepoFile(".github/workflows/agent-rubrics-review.yml"), + readRepoFile(".github/workflows/agent-rubrics-update.yml"), + ]; + const resolverAction = readRepoFile(".github/actions/resolve-agent-provider/action.yml"); + const resolverScript = readRepoFile(".github/actions/resolve-agent-provider/resolve-provider.sh"); + const configurationList = readRepoFile(".agent/docs/customization/configuration-list.md"); + + assert.match(resolverAction, /resolve-provider\.sh/); + assert.match(resolverScript, /DEFAULT_PROVIDER/); + assert.match(resolverScript, /OPENAI_API_KEY/); + assert.match(resolverScript, /CLAUDE_CODE_OAUTH_TOKEN/); + assert.match(resolverScript, /provider=codex/); + assert.match(resolverScript, /provider=claude/); + + assert.match(routerWorkflow, /default:\s*auto/); + assert.doesNotMatch(routerWorkflow, /vars\.AGENT_PROVIDER_(DISPATCH|ANSWER|SKILL)/); + assert.match(routerWorkflow, /required:\s*"false"/); + assert.match(routerWorkflow, /id:\s*dispatch_provider/); + assert.match(routerWorkflow, /id:\s*skill_provider/); + assert.match(routerWorkflow, /agent:\s*\$\{\{\s*steps\.dispatch_provider\.outputs\.provider\s*\}\}/); + assert.match(routerWorkflow, /agent:\s*\$\{\{\s*steps\.skill_provider\.outputs\.provider\s*\}\}/); + assert.match(routerWorkflow, /agent:\s*\$\{\{\s*steps\.provider\.outputs\.provider\s*\}\}/); + + for (const workflow of [implementWorkflow, fixPrWorkflow, selfApprovalWorkflow, ...autonomousWorkflows]) { + assert.match(workflow, /uses: \.\/\.github\/actions\/resolve-agent-provider/); + assert.match(workflow, /default_provider:\s*\$\{\{\s*vars\.AGENT_DEFAULT_PROVIDER \|\|/); + assert.match(workflow, /install_codex:\s*\$\{\{\s*steps\.provider\.outputs\.install_codex\s*\}\}/); + assert.match(workflow, /install_claude:\s*\$\{\{\s*steps\.provider\.outputs\.install_claude\s*\}\}/); + assert.match(workflow, /agent:\s*\$\{\{\s*steps\.provider\.outputs\.provider\s*\}\}/); + assert.match(workflow, /claude_oauth_token:\s*\$\{\{\s*secrets\.CLAUDE_CODE_OAUTH_TOKEN\s*\}\}/); + } + + assert.match(fixPrWorkflow, /lane:\s*fix-pr-\$\{\{\s*steps\.provider\.outputs\.provider\s*\}\}/); + assert.match(reviewWorkflow, /name:\s*Resolve synthesis provider/); + assert.match(reviewWorkflow, /id:\s*synthesis_provider/); + assert.match(reviewWorkflow, /route:\s*review-synthesize/); + assert.match(reviewWorkflow, /default_provider:\s*\$\{\{\s*vars\.AGENT_DEFAULT_PROVIDER \|\| 'auto'\s*\}\}/); + assert.match(reviewWorkflow, /install_codex:\s*\$\{\{\s*steps\.synthesis_provider\.outputs\.install_codex\s*\}\}/); + assert.match(reviewWorkflow, /install_claude:\s*\$\{\{\s*steps\.synthesis_provider\.outputs\.install_claude\s*\}\}/); + assert.match(reviewWorkflow, /agent:\s*\$\{\{\s*steps\.synthesis_provider\.outputs\.provider\s*\}\}/); + assert.match(reviewWorkflow, /openai_api_key:\s*\$\{\{\s*secrets\.OPENAI_API_KEY\s*\}\}/); + assert.doesNotMatch(implementWorkflow, /vars\.AGENT_PROVIDER_IMPLEMENT/); + assert.doesNotMatch(fixPrWorkflow, /vars\.AGENT_PROVIDER_FIX_PR/); + + assert.match(configurationList, /AGENT_DEFAULT_PROVIDER/); + assert.doesNotMatch(configurationList, /AGENT_PROVIDER_IMPLEMENT/); +}); + +test("scheduled workflows evaluate skip gates before provider-dependent jobs", () => { + const dailySummaryWorkflow = readRepoFile(".github/workflows/agent-daily-summary.yml"); + const memoryScanWorkflow = readRepoFile(".github/workflows/agent-memory-scan.yml"); + const memorySyncWorkflow = readRepoFile(".github/workflows/agent-memory-sync.yml"); + const updateWorkflow = readRepoFile(".github/workflows/agent-update.yml"); + const gateAction = readRepoFile(".github/actions/scheduled-activity-gate/action.yml"); + + assert.match(gateAction, /\.agent\/scripts\/resolve-scheduled-activity-gate\.sh/); + assert.doesNotMatch(gateAction, /resolve-gate\.js/); + assert.doesNotMatch(gateAction, /\.agent\/dist\/cli\/resolve-scheduled-activity-gate\.js/); + + assert.match(memoryScanWorkflow, /gate:\n[\s\S]*Resolve scheduled activity gate/); + assert.match(memoryScanWorkflow, /scan:\n\s+needs: gate\n\s+if: needs\.gate\.outputs\.skip != 'true'/); + assert.match(memoryScanWorkflow, /Resolve memory scan provider[\s\S]*Setup agent runtime/); + assert.doesNotMatch(memoryScanWorkflow, /if: steps\.gate\.outputs\.skip != 'true'/); + + assert.match(memorySyncWorkflow, /gate:\n[\s\S]*Resolve scheduled activity gate/); + assert.match(memorySyncWorkflow, /sync:\n\s+needs: gate\n\s+if: needs\.gate\.outputs\.skip != 'true'/); + assert.doesNotMatch(memorySyncWorkflow, /if: steps\.gate\.outputs\.skip != 'true'/); + + assert.match(updateWorkflow, /gate:\n[\s\S]*Resolve scheduled activity gate/); + assert.match(updateWorkflow, /vars\.AGENT_AUTO_UPDATE == 'false'/); + assert.match(updateWorkflow, /"workflow_overrides":\{"agent-update\.yml":"disabled"\}/); + assert.doesNotMatch(updateWorkflow, /Resolve canonical source guard/); + assert.match(updateWorkflow, /Check pending update PR[\s\S]*if: steps\.schedule\.outputs\.skip != 'true'[\s\S]*resolve-pending-update-pr\.sh/); + assert.match(updateWorkflow, /IGNORE_EXISTING_UPDATE_PR:\s*\$\{\{ inputs\.force && 'true' \|\| 'false' \}\}/); + assert.match(updateWorkflow, /update:\n\s+needs: gate\n\s+if: needs\.gate\.outputs\.skip != 'true'/); + assert.match(updateWorkflow, /existing_pr_branch: \$\{\{ steps\.pending\.outputs\.branch \}\}/); + assert.match(updateWorkflow, /ref: \$\{\{ github\.event\.repository\.default_branch \}\}/); + assert.doesNotMatch(updateWorkflow, /ref: \$\{\{ needs\.gate\.outputs\.existing_pr_branch/); + assert.match(updateWorkflow, /Resolve update target checkout[\s\S]*git worktree add -B "\$\{EXISTING_PR_BRANCH\}"/); + assert.match(updateWorkflow, /Resolve update provider[\s\S]*Setup agent runtime/); + assert.match(updateWorkflow, /source_ref:[\s\S]*default:\s*""/); + assert.match(updateWorkflow, /UPDATE_SOURCE_REF:\s*\$\{\{\s*inputs\.source_ref \|\| ''\s*\}\}/); + assert.match(updateWorkflow, /Resolve update source[\s\S]*resolve-update-source\.sh/); + assert.match(updateWorkflow, /Write update source summary[\s\S]*Sepo update source:/); + assert.doesNotMatch(updateWorkflow, /Render update request/); + assert.match(updateWorkflow, /runtime checkout path: \$\{\{ github\.workspace \}\}/); + assert.match(updateWorkflow, /update target path: \$\{\{ steps\.update_target\.outputs\.path \}\}/); + assert.match(updateWorkflow, /update target mode: \$\{\{ steps\.update_target\.outputs\.mode \}\}/); + assert.match(updateWorkflow, /source agent repo\/ref: \$\{\{ steps\.update_source\.outputs\.source_repo \}\}@\$\{\{ steps\.update_source\.outputs\.source_ref \}\}/); + assert.match(updateWorkflow, /source agent SHA: \$\{\{ steps\.update_source\.outputs\.source_sha \}\}/); + assert.match(updateWorkflow, /existing update PR number: \$\{\{ needs\.gate\.outputs\.existing_pr_number \|\| 'none' \}\}/); + assert.match(updateWorkflow, /existing update PR branch: \$\{\{ needs\.gate\.outputs\.existing_pr_branch \|\| 'none' \}\}/); + assert.match(updateWorkflow, /Runtime actions and scripts are loaded from the default-branch checkout/); + assert.match(updateWorkflow, /update that branch and PR in the update target path/); + assert.match(updateWorkflow, /do not check out the existing PR branch in[\s\S]*the runtime checkout path/); + assert.match(updateWorkflow, /Update Sepo from to \$\{\{ steps\.update_source\.outputs\.source_ref \}\}\/\$\{\{ steps\.update_source\.outputs\.source_sha \}\}/); + assert.match(updateWorkflow, /Resolve task timeout[\s\S]*ROUTE: skill[\s\S]*resolve-task-timeout\.js/); + assert.match( + updateWorkflow, + /Run update agent\n\s+id: agent\n\s+timeout-minutes: \$\{\{ fromJson\(steps\.task_timeout\.outputs\.minutes \|\| '30'\) \}\}/, + ); + assert.doesNotMatch(updateWorkflow, /if: steps\.gate\.outputs\.skip != 'true'/); + + assert.match(dailySummaryWorkflow, /pre_gate:\n[\s\S]*Resolve scheduled disabled gate/); + assert.match(dailySummaryWorkflow, /signals:\n\s+needs: pre_gate\n\s+if: needs\.pre_gate\.outputs\.skip != 'true'/); + assert.match( + dailySummaryWorkflow, + /daily-summary:\n\s+needs: signals\n\s+if: needs\.signals\.result == 'success' && needs\.signals\.outputs\.skip != 'true'/, + ); + assert.match(dailySummaryWorkflow, /daily-summary-signals-\$\{\{ github\.run_id \}\}-\$\{\{ github\.run_attempt \}\}/); + assert.match(dailySummaryWorkflow, /Upload summary signals[\s\S]*actions\/upload-artifact@v4/); + assert.match(dailySummaryWorkflow, /Download summary signals[\s\S]*actions\/download-artifact@v4/); + assert.doesNotMatch(dailySummaryWorkflow, /COMMIT_COUNT/); + assert.match(dailySummaryWorkflow, /count=\$\(\(ISSUE_COUNT \+ PULL_COUNT \+ DISCUSSION_COUNT\)\)/); + assert.match( + dailySummaryWorkflow, + /signals:[\s\S]*Resolve GitHub auth[\s\S]*Resolve summary discussion gate[\s\S]*discussion-post-gate[\s\S]*Setup agent runtime for activity signals/, + ); + assert.match(dailySummaryWorkflow, /Setup agent runtime for activity signals\n\s+if: steps\.discussion_gate\.outputs\.skip != 'true'/); + assert.match(dailySummaryWorkflow, /Gather repository signals\n\s+if: steps\.discussion_gate\.outputs\.skip != 'true'/); + assert.match(dailySummaryWorkflow, /Upload summary signals\n\s+if: steps\.discussion_gate\.outputs\.skip != 'true' && steps\.gate\.outputs\.skip != 'true'/); + assert.match(dailySummaryWorkflow, /skip: \$\{\{ steps\.discussion_gate\.outputs\.skip == 'true' && 'true' \|\| steps\.gate\.outputs\.skip \}\}/); + assert.doesNotMatch(dailySummaryWorkflow, /daily-summary:[\s\S]*Resolve summary discussion gate/); + assert.match(dailySummaryWorkflow, /Resolve daily summary provider[\s\S]*Setup selected provider/); + assert.match(dailySummaryWorkflow, /discussion_category:[\s\S]*default:\s*""/); + assert.match( + dailySummaryWorkflow, + /DISCUSSION_CATEGORY:\s*\$\{\{\s*inputs\.discussion_category \|\| vars\.AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY \|\| 'General'\s*\}\}/, + ); + assert.doesNotMatch(dailySummaryWorkflow, /if: steps\.pre_gate\.outputs\.skip != 'true' && steps\.gate\.outputs\.skip != 'true'/); +}); + +test("project manager defaults label application on behind dry-run", () => { + const projectManagerWorkflow = readRepoFile(".github/workflows/agent-project-manager.yml"); + const applyLabelsCli = readRepoFile(".agent/src/cli/apply-project-management-labels.ts"); + const configurationList = readRepoFile(".agent/docs/customization/configuration-list.md"); + const supportedWorkflows = readRepoFile(".agent/docs/architecture/supported-workflows.md"); + + assert.match(projectManagerWorkflow, /apply_labels:[\s\S]*default:\s*"true"/); + assert.match( + projectManagerWorkflow, + /RAW_APPLY_LABELS:\s*\$\{\{ github\.event_name == 'workflow_dispatch' && inputs\.apply_labels \|\| vars\.AGENT_PROJECT_MANAGEMENT_APPLY_LABELS \|\| 'true' \}\}/, + ); + assert.match(projectManagerWorkflow, /apply_labels="\$\(normalize_bool "\$RAW_APPLY_LABELS" true\)"/); + assert.match(applyLabelsCli, /boolEnv\("AGENT_PROJECT_MANAGEMENT_APPLY_LABELS", true\)/); + assert.match(configurationList, /AGENT_PROJECT_MANAGEMENT_APPLY_LABELS[\s\S]*Defaults to `true`/); + assert.match(supportedWorkflows, /Label application defaults enabled[\s\S]*dry-run mode defaults enabled/); +}); + +test("review workflow forwards requested_by to review, rubrics, and synthesis runs", () => { + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const forwardedValue = /requested_by:\s*\$\{\{\s*inputs\.requested_by \|\| github\.actor\s*\}\}/g; + const matches = reviewWorkflow.match(forwardedValue) || []; + + assert.equal(matches.length, 3); +}); + +test("review workflow captures reviewed head as best-effort prepare output", () => { + const workflow = parseYaml(readRepoFile(".github/workflows/agent-review.yml")) as unknown; + assert.ok(isRecord(workflow), "review workflow should parse as a YAML object"); + assert.ok(isRecord(workflow.jobs), "review workflow should define jobs"); + + const prepareJob = workflow.jobs.prepare; + assert.ok(isRecord(prepareJob), "review workflow should define prepare job"); + assert.ok(isRecord(prepareJob.outputs), "prepare job should define outputs"); + assert.equal(prepareJob.outputs.reviewed_head_sha, "${{ steps.capture.outputs.head_sha }}"); + assert.ok(Array.isArray(prepareJob.steps), "prepare job should define steps"); + + const captureStep = prepareJob.steps.find( + (step): step is Record => isRecord(step) && step.id === "capture", + ); + assert.ok(captureStep, "prepare job should capture the reviewed head"); + assert.equal(captureStep["continue-on-error"], true); + assert.equal(captureStep.run, "node .agent/dist/cli/capture-pr-head.js"); + assert.ok(isRecord(captureStep.env), "capture step should define env"); + assert.equal(captureStep.env.TARGET_NUMBER, "${{ inputs.pr_number }}"); + + const reviewJob = workflow.jobs.review; + assert.ok(isRecord(reviewJob), "review workflow should define review job"); + assert.deepEqual(reviewJob.needs, ["prepare"]); + assert.equal(reviewJob.if, "${{ !cancelled() }}"); + + const rubricsReviewJob = workflow.jobs["rubrics-review"]; + assert.ok(isRecord(rubricsReviewJob), "review workflow should define rubrics-review job"); + assert.equal(rubricsReviewJob.needs, undefined); + + const synthesizeJob = workflow.jobs.synthesize; + assert.ok(isRecord(synthesizeJob), "review workflow should define synthesize job"); + assert.deepEqual(synthesizeJob.needs, ["prepare", "review"]); + assert.ok(Array.isArray(synthesizeJob.steps), "synthesize job should define steps"); + + const postCommentStep = synthesizeJob.steps.find( + (step): step is Record => isRecord(step) && step.name === "Post review comment", + ); + assert.ok(postCommentStep, "synthesize job should post the review comment"); + assert.ok(isRecord(postCommentStep.env), "post review comment step should define env"); + assert.equal( + postCommentStep.env.REVIEWED_HEAD_SHA, + "${{ needs.prepare.outputs.reviewed_head_sha }}", + ); +}); + +test("self-approval workflow stays opt-in and read-only until deterministic resolution", () => { + const workflowText = readRepoFile(".github/workflows/agent-self-approve.yml"); + const workflow = parseYaml(workflowText) as unknown; + assert.ok(isRecord(workflow), "self-approval workflow should parse as a YAML object"); + assert.ok(isRecord(workflow.jobs), "self-approval workflow should define jobs"); + const job = workflow.jobs["self-approve"]; + assert.ok(isRecord(job), "self-approval workflow should define self-approve job"); + assert.ok(Array.isArray(job.steps), "self-approval job should define steps"); + assert.match(workflowText, /permissions:\s*\n\s+actions:\s*read/); + + const runStep = job.steps.find( + (step): step is Record => + isRecord(step) && step.name === "Run self-approval agent", + ); + assert.ok(runStep, "self-approval workflow should run the agent"); + assert.ok(isRecord(runStep.with), "self-approval run step should define inputs"); + assert.equal(runStep.with.permission_mode, "approve-reads"); + assert.equal(runStep.with.route, "agent-self-approve"); + assert.equal(runStep.with.github_token, "${{ github.token }}"); + assert.match(workflowText, /AGENT_ALLOW_SELF_APPROVE:\s*\$\{\{\s*vars\.AGENT_ALLOW_SELF_APPROVE \|\| 'false'\s*\}\}/); + assert.match(workflowText, /node \.agent\/dist\/cli\/prepare-self-approve\.js/); + assert.match(workflowText, /node \.agent\/dist\/cli\/resolve-self-approve\.js/); + assert.match(workflowText, /Post self-approval stop[\s\S]*always\(\)[\s\S]*steps\.prepare\.outcome == 'success'[\s\S]*steps\.prepare\.outputs\.should_run != 'true'[\s\S]*steps\.prepare\.outputs\.body_file != ''/); + assert.match(workflowText, /Resolve self-approval result[\s\S]*always\(\)/); + assert.match(workflowText, /Post self-approval status[\s\S]*always\(\)[\s\S]*steps\.result\.outcome == 'failure'/); + assert.match(workflowText, /actions\/upload-artifact@v4/); + assert.match(workflowText, /agent-self-approve-result-\$\{\{ inputs\.pr_number \}\}/); + assert.match(workflowText, /if-no-files-found:\s*ignore/); + assert.doesNotMatch(workflowText, /steps\.result\.outputs\.conclusion == 'request_changes'/); + assert.match(workflowText, /steps\.result\.outcome == 'success' &&\s+inputs\.orchestration_enabled == 'true'/); + assert.match(workflowText, /node \.agent\/dist\/cli\/dispatch-agent-orchestrator\.js/); +}); + +test("self-merge workflow stays opt-in and deterministic", () => { + const workflowText = readRepoFile(".github/workflows/agent-self-merge.yml"); + const workflow = parseYaml(workflowText) as unknown; + assert.ok(isRecord(workflow), "self-merge workflow should parse as a YAML object"); + assert.ok(isRecord(workflow.jobs), "self-merge workflow should define jobs"); + const job = workflow.jobs["self-merge"]; + assert.ok(isRecord(job), "self-merge workflow should define self-merge job"); + assert.ok(Array.isArray(job.steps), "self-merge job should define steps"); + assert.match(workflowText, /permissions:\s*\n\s+actions:\s*read[\s\S]*contents:\s*write[\s\S]*pull-requests:\s*write/); + assert.match(workflowText, /ref:\s*\$\{\{\s*github\.event\.repository\.default_branch\s*\}\}/); + assert.match(workflowText, /AGENT_ALLOW_SELF_MERGE:\s*\$\{\{\s*vars\.AGENT_ALLOW_SELF_MERGE \|\| 'false'\s*\}\}/); + assert.match(workflowText, /node \.agent\/dist\/cli\/resolve-self-merge\.js/); + assert.doesNotMatch(workflowText, /uses: \.\/\.github\/actions\/run-agent-task/); + assert.match(workflowText, /Post self-merge status[\s\S]*steps\.result\.outputs\.status_post == 'true'/); + assert.match(workflowText, /agent-self-merge-result-\$\{\{ inputs\.pr_number \}\}/); + assert.match(workflowText, /SOURCE_ACTION:\s*agent-self-merge/); +}); + +test("review synthesis uses a shared reviews directory contract", () => { + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const reviewPrompt = readRepoFile(".github/prompts/review.md"); + const synthesisPrompt = readRepoFile(".github/prompts/review-synthesize.md"); + const runSource = readRepoFile(".agent/src/run.ts"); + const configurationList = readRepoFile(".agent/docs/customization/configuration-list.md"); + const supportedWorkflows = readRepoFile(".agent/docs/architecture/supported-workflows.md"); + + assert.match(reviewWorkflow, /review:\n\s*# Ordering-only:[\s\S]*?needs:\s*\[prepare\]\n\s*if:\s*\$\{\{\s*!cancelled\(\)\s*\}\}\n\s*# Reviewer lanes are best-effort[\s\S]*?continue-on-error:\s*true/); + assert.match(reviewWorkflow, /synthesize:\n\s*needs:\s*\[prepare,\s*review\]\n\s*if:\s*\$\{\{\s*!cancelled\(\)\s*\}\}/); + assert.match(reviewWorkflow, /find "\$reviews_dir" -type f -name review\.md/); + assert.match(reviewWorkflow, /REVIEWS_DIR:\s*\$\{\{\s*steps\.reviews\.outputs\.reviews_dir\s*\}\}/); + assert.doesNotMatch(reviewWorkflow, /AGENT_INLINE_COMMENT_CLEANUP_MODE/); + assert.match(reviewPrompt, /gh api --paginate repos\/\$\{REPO_SLUG\}\/pulls\/\$\{TARGET_NUMBER\}\/comments/); + assert.match(reviewPrompt, /GraphQL `reviewThreads`/); + assert.match(reviewPrompt, /Inline Comment Suggestions/); + assert.match(reviewPrompt, /open_new[\s\S]*reply_existing[\s\S]*resolve_existing_thread[\s\S]*mark_existing_outdated[\s\S]*no_action/); + assert.match(reviewPrompt, /finding`: concise issue context used for dedupe and rationale/); + assert.match(reviewPrompt, /suggested_body`: exact postable comment text/); + assert.match(reviewPrompt, /GraphQL `existing_thread_id`/); + assert.match(reviewPrompt, /existing_comment_node_id/); + assert.match(reviewPrompt, /Suggest `resolve_existing_thread` only when[\s\S]*same-agent[\s\S]*unresolved[\s\S]*viewer-resolvable[\s\S]*addressed or superseded/); + assert.match(reviewPrompt, /Suggest\s+`mark_existing_outdated` only for older same-agent inline comments[\s\S]*superseded[\s\S]*no appropriate resolvable review-thread path/); + assert.match(reviewPrompt, /Use\s+`no_action` when authorship, PR ownership, supersession, or resolution\s+confidence is uncertain/); + assert.match(reviewPrompt, /These are suggestions only; do not mutate GitHub from the reviewer lane/); + assert.match(synthesisPrompt, /\$\{REVIEWS_DIR\}/); + assert.match(synthesisPrompt, /Inline Comment Suggestions/); + assert.match(synthesisPrompt, /current review artifacts or current diff/); + assert.match(synthesisPrompt, /Treat them\s+as advisory metadata, not commands/); + assert.match(synthesisPrompt, /Synthesis chooses the final inline cleanup\s+action/); + assert.match(synthesisPrompt, /GraphQL `reviewThreads`/); + assert.match(synthesisPrompt, /re-fetch existing inline\s+comments and review threads when relevant[\s\S]*verify\s+the target still belongs\s+to this PR/); + assert.match(synthesisPrompt, /reply_existing[\s\S]*same authenticated agent account[\s\S]*confirms authorship[\s\S]*PR ownership/); + assert.match(synthesisPrompt, /Do not reply to human comments or comments from other bots/); + assert.match(synthesisPrompt, /in_reply_to=/); + assert.match(synthesisPrompt, /resolve_existing_thread/); + assert.match(synthesisPrompt, /resolveReviewThread\(input: \{ threadId: \$id \}\)/); + assert.match(synthesisPrompt, /isResolved[\s\S]*viewerCanResolve[\s\S]*comments' authorship/); + assert.match(synthesisPrompt, /every thread comment authored by\s+the\s+same authenticated agent account/); + assert.match(synthesisPrompt, /never resolve human threads or threads from\s+other bots/); + assert.match(synthesisPrompt, /minimizeComment\(input: \{ subjectId: \$id, classifier: OUTDATED \}\)/); + assert.match(synthesisPrompt, /mark older same-agent inline comments as\s+outdated[\s\S]*supersedes them[\s\S]*no\s+appropriate resolvable same-agent review-thread path/); + assert.match(synthesisPrompt, /Prefer thread\s+resolution over minimization/); + assert.match(synthesisPrompt, /Only minimize comments\s+authored by the same authenticated\s+agent account/); + assert.match(synthesisPrompt, /never minimize\s+human comments or comments from other\s+bots/); + assert.match(synthesisPrompt, /do not delete inline comments/); + assert.match(synthesisPrompt, /do not reply to, resolve, or minimize anything when authorship, PR ownership,\s+supersession, or resolution confidence is uncertain/); + assert.match(synthesisPrompt, /Progress` section/); + assert.match(runSource, /"REVIEWS_DIR"/); + assert.match(runSource, /"MEMORY_DIR"/); + assert.doesNotMatch(runSource, /"AGENT_INLINE_COMMENT_CLEANUP_MODE"/); + assert.doesNotMatch(configurationList, /AGENT_INLINE_COMMENT_CLEANUP_MODE/); + assert.doesNotMatch(supportedWorkflows, /AGENT_INLINE_COMMENT_CLEANUP_MODE/); + assert.doesNotMatch(reviewPrompt, /AGENT_INLINE_COMMENT_CLEANUP_MODE|inline cleanup mode/); + assert.doesNotMatch(synthesisPrompt, /AGENT_INLINE_COMMENT_CLEANUP_MODE|inline cleanup mode/); + assert.doesNotMatch(runSource, /PROMPT_VAR_MEMORY_/); +}); + +test("agent router bypasses dispatch triage for explicit mention slash routes", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const extractContext = readRepoFile(".agent/src/cli/extract-context.ts"); + const resolveDispatch = readRepoFile(".agent/src/cli/resolve-dispatch.ts"); + const implementMetadataPrompt = readRepoFile(".github/prompts/agent-implement-metadata.md"); + + assert.match(extractContext, /setOutput\("requested_route", requestedRoute\)/); + assert.match( + runnerWorkflow, + /steps\.context\.outputs\.should_respond == 'true'[\s\S]*steps\.context\.outputs\.requested_route == ''/, + ); + assert.match( + runnerWorkflow, + /- name: Resolve explicit route authorization[\s\S]*steps\.context\.outputs\.requested_route == 'implement'[\s\S]*steps\.context\.outputs\.target_kind != 'issue'[\s\S]*id:\s*explicit_dispatch[\s\S]*node \.agent\/dist\/cli\/resolve-dispatch\.js/, + ); + assert.match( + runnerWorkflow, + /- name: Generate implement issue metadata[\s\S]*steps\.explicit_dispatch\.outputs\.route == 'implement'[\s\S]*steps\.context\.outputs\.target_kind != 'issue'[\s\S]*continue-on-error:\s*true[\s\S]*permission_mode:\s*approve-all[\s\S]*prompt:\s*agent-implement-metadata/, + ); + assert.match( + runnerWorkflow, + /RESPONSE_FILE:\s*\$\{\{\s*steps\.triage\.outputs\.response_file \|\| steps\.implement_metadata\.outputs\.response_file\s*\}\}/, + ); + assert.match(runnerWorkflow, /REQUESTED_ROUTE:\s*\$\{\{\s*steps\.context\.outputs\.requested_route\s*\}\}/); + assert.match(runnerWorkflow, /base_pr:\s*\$\{\{\s*steps\.dispatch\.outputs\.base_pr\s*\}\}/); + assert.match(resolveDispatch, /buildRequestedRouteDecision/); + assert.match(resolveDispatch, /normalizeImplementIssueMetadata/); + assert.match(implementMetadataPrompt, /Do not derive the title by copying the literal text after `\/implement`/); + assert.match(implementMetadataPrompt, /Ignore earlier prose mentions of `\/implement`/); + assert.match(implementMetadataPrompt, /Omit `base_pr` unless `TARGET_KIND` is `pull_request`/); + assert.match(implementMetadataPrompt, /digits only, with no `#` prefix/); +}); + +test("agent router supports label-triggered route and skill overrides", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const extractContext = readRepoFile(".agent/src/cli/extract-context.ts"); + const labelWorkflow = readRepoFile(".github/workflows/agent-label.yml"); + const entrypointWorkflow = readRepoFile(".github/workflows/agent-entrypoint.yml"); + const approveWorkflow = readRepoFile(".github/workflows/agent-approve.yml"); + + assert.match(runnerWorkflow, /trigger_kind:/); + assert.match(runnerWorkflow, /label_name:/); + assert.match(runnerWorkflow, /requested_skill:/); + assert.match(runnerWorkflow, /needs\.portal\.outputs\.route == 'skill'/); + assert.match(runnerWorkflow, /workflow_call:[\s\S]*outputs:[\s\S]*should_respond:/); + assert.doesNotMatch(runnerWorkflow, /clear-trigger-label:/); + assert.match(runnerWorkflow, /vars\.AGENT_RUNS_ON/); + assert.match(extractContext, /resolveRequestedLabel/); + assert.match(labelWorkflow, /issues:\s+types: \[labeled\]/); + assert.match(labelWorkflow, /pull_request_target:\s+types: \[labeled\]/); + assert.match(labelWorkflow, /cleanup-label:/); + assert.match(labelWorkflow, /needs\.agent\.result == 'success'/); + assert.match(labelWorkflow, /needs\.agent\.outputs\.should_respond == 'true'/); + assert.doesNotMatch(labelWorkflow, /author_association:\s*COLLABORATOR/); + assert.match(labelWorkflow, /\.\/\.github\/actions\/resolve-github-auth/); + assert.match(labelWorkflow, /fallback_token:\s*\$\{\{\s*github\.token\s*\}\}/); + assert.match(labelWorkflow, /actions\/github-script@v7/); + assert.match(labelWorkflow, /github-token:\s*\$\{\{\s*steps\.auth\.outputs\.token\s*\}\}/); + assert.match(labelWorkflow, /github\.rest\.issues\.removeLabel/); + assert.match(labelWorkflow, /vars\.AGENT_RUNS_ON/); + assert.match(entrypointWorkflow, /vars\.AGENT_RUNS_ON/); + assert.match(approveWorkflow, /vars\.AGENT_RUNS_ON/); +}); + +test("agent status label is opt-in and fixed to the AGENT_STATUS_LABEL_ENABLED variable", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const createPrCli = readRepoFile(".agent/src/cli/create-pr.ts"); + const addLabelCli = readRepoFile(".agent/src/cli/add-label.ts"); + const configurationList = readRepoFile(".agent/docs/customization/configuration-list.md"); + const supportedWorkflows = readRepoFile(".agent/docs/architecture/supported-workflows.md"); + + assert.match(configurationList, /AGENT_STATUS_LABEL_ENABLED/); + assert.match(supportedWorkflows, /fixed `agent` status label/); + + assert.match(addLabelCli, /const STATUS_LABEL = "agent"/); + assert.match(addLabelCli, /AGENT_STATUS_LABEL_ENABLED/); + assert.doesNotMatch(addLabelCli, /AGENT_STATUS_LABEL_NAME/); + assert.doesNotMatch(addLabelCli, /AGENT_STATUS_LABEL_COLOR/); + assert.doesNotMatch(addLabelCli, /AGENT_STATUS_LABEL_DESCRIPTION/); + + assert.match( + runnerWorkflow, + /- name: Resolve route[\s\S]*- name: Label handled issue or PR[\s\S]*- name: React with thumbs up/, + ); + assert.match(runnerWorkflow, /vars\.AGENT_STATUS_LABEL_ENABLED == 'true'/); + assert.match(runnerWorkflow, /steps\.dispatch\.outputs\.route != 'unsupported'/); + assert.match( + runnerWorkflow, + /\(steps\.context\.outputs\.target_kind == 'issue' \|\| steps\.context\.outputs\.target_kind == 'pull_request'\)/, + ); + assert.doesNotMatch(runnerWorkflow, /status_label_name:/); + assert.doesNotMatch(runnerWorkflow, /AGENT_STATUS_LABEL_NAME/); + assert.doesNotMatch(runnerWorkflow, /AGENT_STATUS_LABEL_COLOR/); + assert.doesNotMatch(runnerWorkflow, /AGENT_STATUS_LABEL_DESCRIPTION/); + + assert.match(implementWorkflow, /- name: Label source issue[\s\S]*TARGET_KIND: issue/); + assert.match( + implementWorkflow, + /- name: Label generated pull request[\s\S]*TARGET_KIND: pull_request[\s\S]*TARGET_NUMBER: \$\{\{ steps\.pr\.outputs\.pr_number \}\}/, + ); + assert.match( + fixPrWorkflow, + /- name: Label target pull request[\s\S]*vars\.AGENT_STATUS_LABEL_ENABLED == 'true'[\s\S]*steps\.pr\.outputs\.cross_repo != 'true'[\s\S]*steps\.pr\.outputs\.pr_state == 'OPEN'[\s\S]*TARGET_KIND: pull_request/, + ); + assert.match(createPrCli, /setOutput\("pr_number"/); +}); + +test("agent router posts unsupported route summaries directly instead of running the answer agent", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + + assert.match(runnerWorkflow, /Prepare unsupported response/); + assert.match(runnerWorkflow, /needs\.portal\.outputs\.route == 'unsupported'/); + assert.match( + runnerWorkflow, + /- name: Setup agent runtime[\s\S]*needs\.portal\.outputs\.route == 'answer' \|\|[\s\S]*needs\.portal\.outputs\.route == 'unsupported'/, + ); + assert.match( + runnerWorkflow, + /install_codex:\s*\$\{\{\s*needs\.portal\.outputs\.route == 'answer' && steps\.provider\.outputs\.install_codex \|\| 'false'\s*\}\}/, + ); + assert.match( + runnerWorkflow, + /install_claude:\s*\$\{\{\s*needs\.portal\.outputs\.route == 'answer' && steps\.provider\.outputs\.install_claude \|\| 'false'\s*\}\}/, + ); + assert.match(runnerWorkflow, /SUMMARY:\s*\$\{\{\s*needs\.portal\.outputs\.summary\s*\}\}/); + assert.match(runnerWorkflow, /Post unsupported response/); + assert.match( + runnerWorkflow, + /- name: Run answer agent[\s\S]*if:\s*needs\.portal\.outputs\.route == 'answer'/, + ); +}); + +test("agent router dispatches agent-implement directly for explicit implement requests", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const approveWorkflow = readRepoFile(".github/workflows/agent-approve.yml"); + + const implementJobMatch = runnerWorkflow.match( + /\n implement:\n[\s\S]*?(?=\n [a-z][a-z0-9-]*:\n)/, + ); + assert.ok(implementJobMatch, "implement job should exist in agent-router.yml"); + const implementJob = implementJobMatch[0]; + + // Mutual exclusion with the approval job: runs only when the dispatch + // decision said an implementation-like route and no approval gate is needed. + assert.match(implementJob, /needs\.portal\.outputs\.route == 'implement'/); + assert.match(implementJob, /needs\.portal\.outputs\.route == 'create-action'/); + assert.match(implementJob, /needs\.portal\.outputs\.needs_approval == 'false'/); + + // Runtime must be bootstrapped before any node .agent/dist/* calls. + assert.match(implementJob, /uses:\s*\.\/\.github\/actions\/setup-agent-runtime/); + + // Tracking-issue creation + dispatch delegate to CLI helpers in the + // TS backend rather than inline shell. + assert.match( + implementJob, + /- name: Create implementation issue[\s\S]*if:\s*needs\.portal\.outputs\.target_kind != 'issue'[\s\S]*node \.agent\/dist\/cli\/create-issue\.js/, + ); + assert.match( + implementJob, + /- name: Dispatch agent-implement[\s\S]*APPROVAL_COMMENT_URL: ""[\s\S]*node \.agent\/dist\/cli\/dispatch-agent-implement\.js/, + ); + assert.match( + implementJob, + /SESSION_FORK_FROM_THREAD_KEY:\s*\$\{\{ github\.repository \}\}:\$\{\{ needs\.portal\.outputs\.target_kind \}\}:\$\{\{ needs\.portal\.outputs\.target_number \}\}:answer:default/, + ); + assert.match( + implementJob, + /BASE_PR:\s*\$\{\{\s*needs\.portal\.outputs\.base_pr\s*\}\}/, + ); + + // Link-back comment on the originating PR/discussion points at the + // tracking issue that was just created. + assert.match( + implementJob, + /- name: Post link-back to original surface[\s\S]*if:\s*needs\.portal\.outputs\.target_kind != 'issue'[\s\S]*node \.agent\/dist\/cli\/post-response\.js/, + ); + + // agent-approve.yml uses the same CLIs — no duplicate inline shell. + assert.match(approveWorkflow, /node \.agent\/dist\/cli\/create-issue\.js/); + assert.match(approveWorkflow, /node \.agent\/dist\/cli\/dispatch-agent-implement\.js/); + assert.doesNotMatch(approveWorkflow, /actions\/workflows\/\$\{WORKFLOW\}\/dispatches/); +}); + +test("session bundle persistence is configurable through workflow inputs and AGENT_SESSION_BUNDLE_MODE", () => { + const routerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const selfApprovalWorkflow = readRepoFile(".github/workflows/agent-self-approve.yml"); + + assert.match(routerWorkflow, /session_bundle_mode:/); + assert.match(routerWorkflow, /AGENT_SESSION_BUNDLE_MODE/); + assert.match( + routerWorkflow, + /session_bundle_mode:\s*\$\{\{ inputs\.session_bundle_mode \|\| vars\.AGENT_SESSION_BUNDLE_MODE \|\| 'auto' \}\}/, + ); + assert.match(implementWorkflow, /session_bundle_mode:[\s\S]*default:\s*""/); + assert.match(implementWorkflow, /session_fork_from_thread_key:[\s\S]*default:\s*""/); + assert.match(implementWorkflow, /vars\.AGENT_SESSION_BUNDLE_MODE/); + assert.match(fixPrWorkflow, /session_bundle_mode:[\s\S]*default:\s*""/); + assert.match(fixPrWorkflow, /vars\.AGENT_SESSION_BUNDLE_MODE/); + assert.match(reviewWorkflow, /session_bundle_mode:[\s\S]*default:\s*""/); + assert.match(reviewWorkflow, /vars\.AGENT_SESSION_BUNDLE_MODE/); + assert.match(selfApprovalWorkflow, /session_bundle_mode:[\s\S]*default:\s*""/); + assert.match(selfApprovalWorkflow, /vars\.AGENT_SESSION_BUNDLE_MODE/); +}); + +test("workflows use granular CLI helpers for post-processing", () => { + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/add-label\.js/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/verify\.js/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/parse-response\.js/); + assert.match(implementWorkflow, /steps\.response\.outputs\.commit_message/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/commit\.js/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/create-pr\.js/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/post-comment\.js/); + assert.match(implementWorkflow, /base_branch:/); + assert.match(implementWorkflow, /base_pr:/); + assert.match(implementWorkflow, /node \.agent\/dist\/cli\/resolve-implementation-base\.js/); + assert.match(implementWorkflow, /GH_TOKEN:\s*\$\{\{ steps\.auth\.outputs\.token \}\}/); + assert.match(implementWorkflow, /http\.\$\{GITHUB_SERVER_URL\}\/\.extraheader=AUTHORIZATION: basic \$\{AUTH_HEADER\}/); + assert.match(implementWorkflow, /fetch origin "refs\/heads\/\$\{BASE_BRANCH\}"/); + assert.match(implementWorkflow, /BASE_BRANCH:\s*\$\{\{ env\.BASE_BRANCH \}\}/); + + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/verify\.js/); + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/detect-head-change\.js/); + assert.ok( + fixPrWorkflow.indexOf("node .agent/dist/cli/detect-head-change.js") + < fixPrWorkflow.indexOf("node .agent/dist/cli/verify.js"), + ); + assert.match(fixPrWorkflow, /HEAD_CHANGED:\s*\$\{\{ steps\.head\.outputs\.head_changed \}\}/); + assert.match(fixPrWorkflow, /VERIFY_BASE_SHA:\s*\$\{\{ steps\.pr\.outputs\.head_sha \}\}/); + assert.match(fixPrWorkflow, /steps\.commit\.outcome == 'failure'/); + assert.match(fixPrWorkflow, /steps\.push-head\.outcome == 'failure'/); + assert.match(fixPrWorkflow, /steps\.response\.outputs\.commit_message/); + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/commit\.js/); + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/push-pr-head\.js/); + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/add-label\.js/); + assert.match(fixPrWorkflow, /node \.agent\/dist\/cli\/post-comment\.js/); + assert.match(fixPrWorkflow, /AGENT_COLLAPSE_OLD_REVIEWS:\s*\$\{\{ vars\.AGENT_COLLAPSE_OLD_REVIEWS \}\}/); + const unsupportedFixPrStatusStart = fixPrWorkflow.indexOf("- name: Post unsupported status"); + const orchestrateHandoffStart = fixPrWorkflow.indexOf("- name: Orchestrate automation handoff"); + assert.ok(unsupportedFixPrStatusStart >= 0); + assert.ok(orchestrateHandoffStart > unsupportedFixPrStatusStart); + const unsupportedFixPrStatusStep = fixPrWorkflow.slice( + unsupportedFixPrStatusStart, + orchestrateHandoffStart, + ); + assert.match(unsupportedFixPrStatusStep, /run: node \.agent\/dist\/cli\/post-comment\.js/); + assert.match(unsupportedFixPrStatusStep, /AGENT_COLLAPSE_OLD_REVIEWS:\s*\$\{\{ vars\.AGENT_COLLAPSE_OLD_REVIEWS \}\}/); + assert.match(unsupportedFixPrStatusStep, /COMMENT_TARGET:\s*pr/); + assert.match(unsupportedFixPrStatusStep, /ROUTE:\s*fix-pr/); + assert.match(unsupportedFixPrStatusStep, /STATUS:\s*unsupported/); + assert.doesNotMatch(unsupportedFixPrStatusStep, /gh pr comment/); + assert.match( + fixPrWorkflow, + /REQUESTED_BY:\s*\$\{\{\s*inputs\.orchestration_enabled == 'true' && \(vars\.AGENT_HANDLE \|\| '@sepo-agent'\) \|\| inputs\.requested_by \|\| github\.actor\s*\}\}/, + ); + + assert.match(reviewWorkflow, /node \.agent\/dist\/cli\/post-comment\.js/); + assert.match(reviewWorkflow, /AGENT_COLLAPSE_OLD_REVIEWS:\s*\$\{\{ vars\.AGENT_COLLAPSE_OLD_REVIEWS \}\}/); +}); + +test("shared run-agent-task action exists and requires explicit prompt/skill/lane/session_policy inputs", () => { + const action = readRepoFile(".github/actions/run-agent-task/action.yml"); + + assert.match(action, /name: Run Agent Task/); + assert.match(action, /prompt:/); + assert.match(action, /skill:/); + assert.match(action, /skill_root:/); + assert.match(action, /lane:/); + assert.match(action, /session_policy:/); + const sessionPolicyBlock = action.match(/session_policy:[\s\S]*?(?=^ [a-z_]+:|^outputs:)/m)?.[0] || ""; + assert.match(sessionPolicyBlock, /required:\s*true/); + assert.doesNotMatch(sessionPolicyBlock, /default:/); + assert.match(action, /PROMPT_NAME/); + assert.match(action, /SKILL_NAME/); + assert.match(action, /SKILL_ROOT/); + assert.match(action, /LANE/); + assert.match(action, /SESSION_POLICY/); + assert.match(action, /\.agent\/dist\/run\.js/); +}); + +test("shared setup-agent-runtime action exists and is referenced by reusable workflows", () => { + const action = readRepoFile(".github/actions/setup-agent-runtime/action.yml"); + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + + assert.match(action, /name: Setup Agent Runtime/); + assert.match(action, /actions\/setup-node/); + assert.match(action, /npm ci/); + assert.match(action, /npm run build/); + assert.match(runnerWorkflow, /\.\/\.github\/actions\/setup-agent-runtime/); +}); + +test("skill route uses the composite setup action for path and setup checks", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const setupAction = readRepoFile(".github/actions/run-skill-setup/action.yml"); + const skillJobStart = runnerWorkflow.indexOf(" skill:\n needs: portal"); + const approvalJobStart = runnerWorkflow.indexOf(" approval:", skillJobStart); + assert.ok(skillJobStart >= 0); + assert.ok(approvalJobStart > skillJobStart); + const skillWorkflow = runnerWorkflow.slice(skillJobStart, approvalJobStart); + const optionalProviderStart = skillWorkflow.indexOf("- name: Resolve skill provider"); + const runtimeStart = skillWorkflow.indexOf("- name: Setup agent runtime"); + const checkStart = skillWorkflow.indexOf("- name: Check skill"); + const requireProviderStart = skillWorkflow.indexOf("- name: Require skill provider"); + const setupStart = skillWorkflow.indexOf("- name: Run skill setup"); + + assert.match(skillWorkflow, /\.\/\.github\/actions\/run-skill-setup/); + assert.match(skillWorkflow, /trusted_ref:\s*\$\{\{ !startsWith\(github\.ref, 'refs\/pull\/'\) \}\}/); + assert.match(skillWorkflow, /skill_root:\s*\$\{\{ inputs\.skill_root \}\}/); + assert.ok(optionalProviderStart >= 0); + assert.ok(runtimeStart > optionalProviderStart); + assert.ok(checkStart > runtimeStart); + assert.ok(requireProviderStart > checkStart); + assert.ok(setupStart > requireProviderStart); + assert.match(skillWorkflow, /required:\s*"false"/); + assert.doesNotMatch(skillWorkflow, /resolve-skill\.js/); + assert.match(skillWorkflow, /run_setup:\s*"false"/); + assert.match(skillWorkflow, /run_setup:\s*"true"/); + assert.match(skillWorkflow, /steps\.skill_setup\.outcome == 'success'/); + assert.match(skillWorkflow, /steps\.skill_check\.outputs\.exists == 'false'/); + assert.match(setupAction, /name: Run Skill Setup/); + assert.match(setupAction, /run_setup:/); + assert.doesNotMatch(setupAction, /node \.agent\/dist\/cli\/run-skill-setup\.js/); + assert.match(setupAction, /if \[ ! -f "\$skill_file" \]/); + assert.match(setupAction, /if \[ ! -f "\$setup_file" \]/); + assert.match(setupAction, /Refusing to run .*untrusted PR checkout/); + assert.match(setupAction, /bash "\$setup_file"/); +}); + +test("shared auth action supports the built-in hosted OIDC broker mode", () => { + const action = readRepoFile(".github/actions/resolve-github-auth/action.yml"); + const oidcScript = readRepoFile(".github/actions/resolve-github-auth/exchange-oidc.sh"); + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const approveWorkflow = readRepoFile(".github/workflows/agent-approve.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const entrypointWorkflow = readRepoFile(".github/workflows/agent-entrypoint.yml"); + const labelWorkflow = readRepoFile(".github/workflows/agent-label.yml"); + const memoryBootstrapWorkflow = readRepoFile(".github/workflows/agent-memory-bootstrap.yml"); + + assert.doesNotMatch(action, /oidc_exchange_url:/); + assert.doesNotMatch(action, /oidc_audience:/); + assert.match(action, /Validate direct GitHub App inputs/); + assert.match(action, /app_id and app_private_key must be configured together/); + assert.match(action, /bash "\$\{GITHUB_ACTION_PATH\}\/exchange-oidc\.sh"/); + assert.match(action, /https:\/\/oidc\.self-evolving\.app/); + assert.match(action, /OIDC_AUDIENCE:\s*sepo/); + + assert.match(oidcScript, /ACTIONS_ID_TOKEN_REQUEST_URL/); + assert.match(oidcScript, /ACTIONS_ID_TOKEN_REQUEST_TOKEN/); + assert.match(oidcScript, /oidc_request_url=\"\$\{ACTIONS_ID_TOKEN_REQUEST_URL\}&audience=\$\{OIDC_AUDIENCE\}\"/); + assert.match(oidcScript, /for cmd in curl jq/); + assert.match(oidcScript, /run_with_retries\(\)/); + assert.match(oidcScript, /jq -r '\.value \/\/ empty' 2>\/dev\/null \|\| true/); + assert.match(oidcScript, /jq -r '\.token \/\/ \.app_token \/\/ empty' .*2>\/dev\/null \|\| true/); + assert.match(oidcScript, /--max-time 30/); + assert.match(oidcScript, /auth_mode=oidc_broker/); + + for (const workflow of [ + runnerWorkflow, + approveWorkflow, + implementWorkflow, + fixPrWorkflow, + reviewWorkflow, + entrypointWorkflow, + labelWorkflow, + memoryBootstrapWorkflow, + ]) { + assert.match(workflow, /id-token:\s*write/); + assert.doesNotMatch(workflow, /AGENT_OIDC_EXCHANGE_URL/); + assert.doesNotMatch(workflow, /AGENT_OIDC_AUDIENCE/); + } +}); + +test("shared run-agent-task action wires session bundle restore and upload around the agent run", () => { + const action = readRepoFile(".github/actions/run-agent-task/action.yml"); + const runSource = readRepoFile(".agent/src/run.ts"); + + assert.match(action, /session_bundle_mode:/); + assert.match(action, /session_bundle_retention_days:/); + assert.match(action, /session_fork_from_thread_key:/); + assert.match(action, /Restore session bundle/); + assert.match(action, /Restore session bundle[\s\S]*continue-on-error:\s*true/); + assert.match(action, /node \.agent\/dist\/cli\/session-restore\.js/); + assert.match(action, /Prepare session bundle/); + assert.match(action, /node \.agent\/dist\/cli\/session-backup\.js/); + assert.match(action, /Prepare session bundle[\s\S]*steps\.run\.outputs\.exit_code == '0'/); + assert.match(action, /Upload session bundle artifact[\s\S]*steps\.run\.outputs\.exit_code == '0'/); + assert.match(action, /actions\/upload-artifact@v4/); + assert.match(action, /Register session bundle artifact[\s\S]*steps\.run\.outputs\.exit_code == '0'/); + assert.match(action, /node \.agent\/dist\/cli\/session-register\.js/); + assert.match(action, /resume_status:/); + assert.match(action, /session_bundle_restore_status:/); + assert.match(action, /session_fork_restore_status:/); + assert.match(action, /SESSION_FORK_FROM_THREAD_KEY:\s*\$\{\{\s*inputs\.session_fork_from_thread_key\s*\}\}/); + assert.match(action, /SESSION_FORK_ACPX_SESSION_ID:\s*\$\{\{\s*steps\.restore\.outputs\.fork_acpx_session_id\s*\}\}/); + + const parsedAction = parseYaml(action) as unknown; + assert.ok(isRecord(parsedAction), "run-agent-task action should parse as a YAML object"); + assert.ok(isRecord(parsedAction.runs), "run-agent-task action should define runs"); + assert.ok(Array.isArray(parsedAction.runs.steps), "run-agent-task action should define steps"); + const runStep = parsedAction.runs.steps.find( + (step): step is Record => isRecord(step) && step.name === "Run agent task", + ); + assert.ok(runStep, "run-agent-task action should include the Run agent task step"); + assert.ok(isRecord(runStep.env), "Run agent task step should define env"); + assert.equal(runStep.env.SESSION_BUNDLE_MODE, "${{ inputs.session_bundle_mode }}"); + assert.match(runSource, /parseSessionBundleMode\(process\.env\.SESSION_BUNDLE_MODE\)/); + assert.match( + runSource, + /preserveExecSession:\s*sessionPolicy === "track-only" &&\s*shouldBackupSessionBundles\(sessionBundleMode, sessionPolicy\)/, + ); +}); + +test("workflows declare explicit session policies", () => { + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const selfApprovalWorkflow = readRepoFile(".github/workflows/agent-self-approve.yml"); + + assert.match(runnerWorkflow, /prompt:\s*dispatch[\s\S]*session_policy:\s*none/); + assert.match(runnerWorkflow, /prompt:\s*answer[\s\S]*session_policy:\s*resume-best-effort/); + assert.match(fixPrWorkflow, /prompt:\s*fix-pr[\s\S]*session_policy:\s*resume-best-effort/); + assert.match(implementWorkflow, /prompt:\s*\$\{\{ env\.IMPLEMENTATION_PROMPT \}\}[\s\S]*session_fork_from_thread_key:\s*\$\{\{ inputs\.session_fork_from_thread_key \}\}/); + assert.match(implementWorkflow, /route:\s*\$\{\{ env\.IMPLEMENTATION_ROUTE \}\}[\s\S]*session_policy:\s*\$\{\{ inputs\.session_fork_from_thread_key != '' && 'resume-best-effort' \|\| 'track-only' \}\}/); + assert.match(reviewWorkflow, /prompt:\s*review[\s\S]*session_policy:\s*track-only/); + assert.match(reviewWorkflow, /agent-rubrics-review\.yml/); + assert.match(reviewWorkflow, /prompt:\s*review-synthesize[\s\S]*session_policy:\s*track-only/); + assert.match(selfApprovalWorkflow, /prompt:\s*agent-self-approve[\s\S]*session_policy:\s*track-only/); +}); + +test("review workflow declares distinct lanes for reviewer jobs and synthesis", () => { + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + + assert.match(reviewWorkflow, /lane:\s*claude-review/); + assert.match(reviewWorkflow, /lane:\s*codex-review/); + assert.match(reviewWorkflow, /lane:\s*synthesize/); +}); + +test("workflow docs record the minimal metadata contract and developer notes", () => { + const keyConcepts = readRepoFile(".agent/docs/technical-details/key-concepts.md"); + const memoryArchitecture = readRepoFile(".agent/docs/architecture/memory.md"); + const rubricsArchitecture = readRepoFile(".agent/docs/architecture/rubrics.md"); + const rubricsInitializationWorkflow = readRepoFile(".github/workflows/agent-rubrics-initialization.yml"); + const rubricsInitializationPrompt = readRepoFile(".github/prompts/rubrics-initialization.md"); + const supportedWorkflows = readRepoFile(".agent/docs/architecture/supported-workflows.md"); + const requestLifecycle = readRepoFile(".agent/docs/architecture/request-lifecycle.md"); + const configurationList = readRepoFile(".agent/docs/customization/configuration-list.md"); + const skillsDocs = readRepoFile(".agent/docs/customization/skills.md"); + const existingRepoInstall = readRepoFile(".agent/docs/deployment/install-existing-repository.md"); + const developerNotes = readRepoFile(".agent/docs/technical-details/developer-notes.md"); + + assert.match(keyConcepts, /### RuntimeEnvelope/); + assert.match(keyConcepts, /Envelope version, currently `1`/); + assert.match(keyConcepts, /`thread_key`/); + assert.match(keyConcepts, /repo:target_kind:target_number:route:lane/); + assert.match(keyConcepts, /`issue`, `pull_request`, `discussion`, or `repository`/); + assert.match(keyConcepts, /target_number=0/); + + assert.match(supportedWorkflows, /agent-label\.yml/); + assert.match(supportedWorkflows, /agent-branch-cleanup\.yml/); + assert.match(supportedWorkflows, /### Core workflows/i); + assert.match(supportedWorkflows, /### Repository memory workflows/i); + assert.match(supportedWorkflows, /Agent \/ Memory \/ Initialization/); + assert.match(supportedWorkflows, /Agent \/ Memory \/ Sync GitHub Artifacts/); + assert.match(supportedWorkflows, /Agent \/ Memory \/ Record PR Closure/); + assert.match(supportedWorkflows, /Agent \/ Memory \/ Curate Recent Activity/); + assert.match(supportedWorkflows, /Agent \/ Memory \/ Initialization[\s\S]*\|\s*Auto\s*\|/); + assert.match(supportedWorkflows, /Agent \/ Rubrics \/ Review/); + assert.match(supportedWorkflows, /Agent \/ Rubrics \/ Initialization/); + assert.match(supportedWorkflows, /Agent \/ Rubrics \/ Update/); + assert.doesNotMatch( + supportedWorkflows.match(/### Core workflows[\s\S]*?### Repository memory workflows/)?.[0] || "", + /agent-rubrics-/, + ); + assert.match(supportedWorkflows, /agent\/s\//); + assert.match(supportedWorkflows, /removes[\s\S]*triggering `agent\/\*` label/i); + assert.match(supportedWorkflows, /strips code blocks[\s\S]*quoted text/i); + assert.match(supportedWorkflows, /OWNER[\s\S]*MEMBER[\s\S]*COLLABORATOR[\s\S]*CONTRIBUTOR/); + assert.match(memoryArchitecture, /Agent \/ Memory \/ Initialization[\s\S]*\|\s*Auto\s*\|/); + assert.match(rubricsArchitecture, /agent\/rubrics/); + assert.match(rubricsArchitecture, /AGENT_RUBRICS_POLICY/); + assert.match(rubricsArchitecture, /agent\/memory` stores agent\/project continuity/i); + assert.match(rubricsArchitecture, /Agent \/ Rubrics \/ Initialization/); + assert.match(rubricsInitializationWorkflow, /^name: Agent \/ Rubrics \/ Initialization$/m); + assert.match(rubricsInitializationWorkflow, /Reject existing rubrics branch/); + assert.match(rubricsInitializationWorkflow, /prompt:\s*rubrics-initialization/); + assert.match(rubricsInitializationWorkflow, /route:\s*rubrics-initialization/); + assert.match(rubricsInitializationWorkflow, /rubrics_mode_override:\s*'enabled'/); + assert.match(rubricsInitializationWorkflow, /initialization_context:/); + assert.match(rubricsInitializationWorkflow, /rubrics_ref:[\s\S]*default: agent\/rubrics/); + assert.match(rubricsInitializationWorkflow, /inputs\.rubrics_ref \|\| vars\.AGENT_RUBRICS_REF \|\| 'agent\/rubrics'/); + assert.doesNotMatch(rubricsInitializationWorkflow, /description: "GitHub login that requested the run"/); + assert.doesNotMatch(rubricsInitializationWorkflow, /^ session_bundle_mode:/m); + assert.match(rubricsInitializationWorkflow, /requested_by:\s*\$\{\{\s*github\.repository_owner\s*\}\}/); + assert.match(rubricsInitializationWorkflow, /session_bundle_mode:\s*\$\{\{\s*vars\.AGENT_SESSION_BUNDLE_MODE \|\| 'auto'\s*\}\}/); + assert.match(rubricsInitializationPrompt, /Initialization context:/); + assert.match(rubricsInitializationPrompt, /OWNER[\s\S]*MEMBER[\s\S]*COLLABORATOR/); + assert.match(rubricsArchitecture, /Only rubric initialization bootstraps a missing branch/); + assert.match(rubricsArchitecture, /Dispatch triage is always rubric-disabled/); + assert.match(rubricsArchitecture, /honor `AGENT_RUBRICS_POLICY`/); + assert.match(existingRepoInstall, /cannot silently skip persistence/); + + assert.match(requestLifecycle, /route access follows the configured trigger access policy/); + assert.match(requestLifecycle, /agent\/--\/-/); + + assert.match(configurationList, /AGENT_RUNS_ON/); + assert.match(configurationList, /AGENT_TASK_TIMEOUT_POLICY/); + assert.match(configurationList, /Values must be 1-360 minutes/); + assert.match(configurationList, /AGENT_MEMORY_POLICY/); + assert.match(configurationList, /AGENT_MEMORY_REF/); + assert.match(configurationList, /AGENT_RUBRICS_POLICY/); + assert.match(configurationList, /AGENT_RUBRICS_REF/); + assert.match(configurationList, /AGENT_RUBRICS_LIMIT/); + assert.match(configurationList, /AGENT_SESSION_BUNDLE_MODE/); + assert.match(configurationList, /AGENT_AUTOMATION_MODE/); + assert.match(configurationList, /AGENT_AUTOMATION_MAX_ROUNDS/); + assert.match(configurationList, /AGENT_AUTO_UPDATE/); + assert.match(configurationList, /AGENT_STATUS_LABEL_ENABLED/); + + assert.match(existingRepoInstall, /open a normal PR in the target repository/i); + assert.match(existingRepoInstall, /`\.github\/`/); + assert.match(existingRepoInstall, /workflows, composite actions, and prompt templates/i); + assert.match(existingRepoInstall, /Agent \/ Memory \/ Initialization/); + assert.match(existingRepoInstall, /Alternative: local memory bootstrap/); + assert.match(existingRepoInstall, /first-run initializer/i); + assert.match(existingRepoInstall, /does not require[\s\S]*agent\/memory[\s\S]*to exist yet/i); + assert.match(existingRepoInstall, /rejects the run if[\s\S]*already exists/i); + assert.match(existingRepoInstall, /initial GitHub artifact sync/i); + assert.match(existingRepoInstall, /recent-activity curation inline/i); + assert.match(existingRepoInstall, /Agent \/ Rubrics \/ Initialization/); + assert.match(existingRepoInstall, /supplied context/i); + + assert.match(developerNotes, /## Testing/); + assert.match(developerNotes, /cd \.agent[\s\S]*npm test/); + assert.match(developerNotes, /## Known limitations/); + assert.match(developerNotes, /hosted Sepo App path only works/); + assert.match(developerNotes, /selected-repository installation/); + assert.match(skillsDocs, /`skill_root`/); + assert.match(skillsDocs, /\/skill/); + assert.match(skillsDocs, /setup\.sh/); + assert.match(skillsDocs, /agent-router\.yml/); + assert.match(developerNotes, /lazy blockquote/); + assert.match(developerNotes, /lightweight post-agent check/); +}); + +test("create-action prompt uses native workflows with shared expiration and runtime guardrails", () => { + const prompt = readRepoFile(".github/prompts/agent-create-action.md"); + const docs = readRepoFile(".agent/docs/customization/creating-your-own-actions.md"); + const template = readRepoFile(".agent/action-templates/agent-action-template.yml"); + const internalActions = readRepoFile(".agent/docs/actions/internal-actions.md"); + const action = readRepoFile(".github/actions/check-agent-action-expiration/action.yml"); + const script = readRepoFile(".github/actions/check-agent-action-expiration/check-expiration.sh"); + + for (const content of [prompt, docs]) { + assert.match(content, /\.agent\/action-templates\/agent-action-template\.yml/); + assert.match(content, /check-agent-action-expiration/); + assert.match(content, /steps\.expiration\.outputs\.expired != 'true'/); + assert.match(content, /issues: write/); + assert.doesNotMatch(content, /date -u -d/); + } + + assert.match(template, /uses: \.\/\.github\/actions\/check-agent-action-expiration/); + assert.match(template, /uses: \.\/\.github\/actions\/resolve-github-auth/); + assert.match(template, /uses: \.\/\.github\/actions\/resolve-agent-provider/); + assert.match(template, /uses: \.\/\.github\/actions\/setup-agent-runtime/); + assert.match(template, /uses: \.\/\.github\/actions\/run-agent-task/); + assert.match(template, /steps\.expiration\.outputs\.expired != 'true'/); + assert.match(template, /permission_mode:\s*approve-all/); + assert.match(template, /memory_mode_override:\s*read-only/); + assert.match(template, /session_policy:\s*track-only/); + assert.match(template, /Post report to issue/); + assert.match(template, /add issue write permission/i); + assert.doesNotMatch(template, /^\s*issues:\s*write\s*$/m); + assert.doesNotMatch(template, /date -u -d/); + + assert.match(internalActions, /check-agent-action-expiration/); + assert.match(action, /expires_at:/); + assert.match(action, /check-expiration\.sh/); + assert.match(script, /date -u \+%Y-%m-%d/); + assert.doesNotMatch(script, /date -u -d/); +}); + +test("agent implement prompt input falls back to implementation route", () => { + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const implementationPromptDefaults = + implementWorkflow.match(/implementation_prompt:[\s\S]*?default:\s*""/g) || []; + + assert.equal(implementationPromptDefaults.length, 2); + assert.match( + implementWorkflow, + /IMPLEMENTATION_PROMPT:\s*\$\{\{\s*inputs\.implementation_prompt \|\| inputs\.implementation_route \|\| 'implement'\s*\}\}/, + ); +}); + +test("execution workflows expose automation handoff inputs", () => { + const entrypointWorkflow = readRepoFile(".github/workflows/agent-entrypoint.yml"); + const labelWorkflow = readRepoFile(".github/workflows/agent-label.yml"); + const runnerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const approveWorkflow = readRepoFile(".github/workflows/agent-approve.yml"); + const orchestratorWorkflow = readRepoFile(".github/workflows/agent-orchestrator.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const selfApprovalWorkflow = readRepoFile(".github/workflows/agent-self-approve.yml"); + const runSource = readRepoFile(".agent/src/run.ts"); + const handoffSource = readRepoFile(".agent/src/handoff.ts"); + const orchestrateHandoffCli = readRepoFile(".agent/src/cli/orchestrate-handoff.ts"); + const fixPrPrompt = readRepoFile(".github/prompts/agent-fix-pr.md"); + const orchestratorPrompt = readRepoFile(".github/prompts/agent-orchestrator.md"); + const orchestratorDoc = readRepoFile(".agent/docs/technical-details/agent-orchestrator.md"); + + assert.match(entrypointWorkflow, /automation_mode:\s*\$\{\{ vars\.AGENT_AUTOMATION_MODE \|\| 'agent' \}\}/); + assert.match(labelWorkflow, /automation_mode:\s*\$\{\{ vars\.AGENT_AUTOMATION_MODE \|\| 'agent' \}\}/); + assert.match(runnerWorkflow, /automation_mode:[\s\S]*default:\s*"agent"/); + assert.match(approveWorkflow, /AUTOMATION_MODE:\s*\$\{\{ vars\.AGENT_AUTOMATION_MODE \|\| 'agent' \}\}/); + assert.match(orchestratorWorkflow, /name: Agent \/ Orchestrator/); + assert.match(orchestratorWorkflow, /source_run_id:/); + assert.match(orchestratorWorkflow, /issues: write/); + assert.match(orchestratorWorkflow, /uses: \.\/\.github\/actions\/resolve-agent-provider/); + assert.match(orchestratorWorkflow, /route:\s*orchestrator/); + assert.match(orchestratorWorkflow, /node \.agent\/dist\/cli\/orchestrator-preflight\.js/); + assert.match(orchestratorWorkflow, /Check handoff preflight[\s\S]*AUTHOR_ASSOCIATION:/); + assert.match(orchestratorWorkflow, /Check handoff preflight[\s\S]*ACCESS_POLICY:/); + assert.match( + orchestratorWorkflow, + /Plan next action with agent[\s\S]*if:\s*\$\{\{\s*steps\.preflight\.outputs\.planner_enabled == 'true'\s*\}\}/, + ); + assert.match(orchestratorWorkflow, /install_claude:\s*\$\{\{\s*steps\.provider\.outputs\.install_claude\s*\}\}/); + assert.match(orchestratorWorkflow, /prompt:\s*orchestrator/); + assert.match(orchestratorWorkflow, /permission_mode:\s*approve-all/); + assert.match(orchestratorWorkflow, /session_policy:\s*resume-best-effort/); + assert.match(orchestratorWorkflow, /continue-on-error:\s*true/); + assert.match(orchestratorWorkflow, /rubrics_mode_override:\s*read-only/); + assert.match(orchestratorWorkflow, /agent:\s*\$\{\{\s*steps\.provider\.outputs\.provider\s*\}\}/); + assert.match(orchestratorWorkflow, /node \.agent\/dist\/cli\/orchestrate-handoff\.js/); + + for (const workflow of [implementWorkflow, fixPrWorkflow, reviewWorkflow, selfApprovalWorkflow]) { + assert.match(workflow, /automation_mode:/); + assert.match(workflow, /automation_current_round:/); + assert.match(workflow, /automation_max_rounds:/); + assert.match(workflow, /orchestration_enabled:/); + assert.match(workflow, /inputs\.orchestration_enabled == 'true'/); + assert.match(workflow, /node \.agent\/dist\/cli\/dispatch-agent-orchestrator\.js/); + } + + assert.match(runnerWorkflow, /needs\.portal\.outputs\.route == 'orchestrate'/); + assert.match(runnerWorkflow, /SOURCE_ACTION:\s*orchestrate/); + assert.match(runnerWorkflow, /TARGET_KIND:\s*\$\{\{ needs\.portal\.outputs\.target_kind \}\}/); + assert.match(runnerWorkflow, /node \.agent\/dist\/cli\/dispatch-agent-orchestrator\.js/); + assert.match(reviewWorkflow, /id: post_comment/); + assert.match(reviewWorkflow, /RESPONSE_FILE:\s*\$\{\{ steps\.synthesis\.outputs\.response_file \}\}/); + assert.match(reviewWorkflow, /steps\.post_comment\.outcome == 'success'/); + assert.match(orchestratorWorkflow, /PLANNER_RESPONSE_FILE:\s*\$\{\{ steps\.planner\.outputs\.response_file \}\}/); + assert.match(orchestratorWorkflow, /base_branch:/); + assert.match(orchestratorWorkflow, /base_pr:/); + assert.match(orchestratorWorkflow, /source_handoff_context:/); + assert.match(orchestratorWorkflow, /AGENT_COLLAPSE_OLD_REVIEWS:\s*\$\{\{ vars\.AGENT_COLLAPSE_OLD_REVIEWS \}\}/); + assert.match(orchestratorWorkflow, /BASE_BRANCH:\s*\$\{\{ inputs\.base_branch \}\}/); + assert.match(orchestratorWorkflow, /SOURCE_HANDOFF_CONTEXT:\s*\$\{\{ inputs\.source_handoff_context \}\}/); + assert.match(orchestratorWorkflow, /ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT:\s*\$\{\{ inputs\.source_handoff_context \}\}/); + assert.match(orchestrateHandoffCli, /resolveEffectiveBaseInputs/); + assert.match(orchestrateHandoffCli, /baseBranch:\s*decision\.baseBranch \|\| baseBranch/); + assert.match(orchestrateHandoffCli, /basePr:\s*decision\.basePr \|\| basePr/); + assert.match(orchestrateHandoffCli, /base_branch:\s*effectiveBaseBranch/); + assert.match(orchestrateHandoffCli, /base_pr:\s*effectiveBasePr/); + assert.match(orchestrateHandoffCli, /set only one of base_branch or base_pr for implementation/); + assert.match(orchestrateHandoffCli, /sourceHandoffContext/); + assert.match(orchestratorWorkflow, /target_kind:/); + assert.match(orchestratorWorkflow, /TARGET_KIND:/); + assert.match(orchestrateHandoffCli, /orchestration_enabled:\s*"true"/); + assert.match(orchestrateHandoffCli, /automationMode === "disabled" \? "heuristics" : automationMode/); + assert.match(orchestrateHandoffCli, /orchestrator_context:\s*decision\.handoffContext/); + assert.match(orchestrateHandoffCli, /agent-self-approve\.yml/); + assert.match(orchestrateHandoffCli, /agent-self-merge\.yml/); + assert.match(handoffSource, /Task for fix-pr/); + assert.match(orchestrateHandoffCli, /collapsePreviousHandoffComments/); + assert.match(orchestrateHandoffCli, /manual orchestrate start on issue; dispatching implement/); + assert.match(fixPrWorkflow, /orchestrator_context:/); + assert.match(fixPrWorkflow, /ORCHESTRATOR_CONTEXT:\s*\$\{\{ inputs\.orchestrator_context \}\}/); + assert.match(fixPrPrompt, /\$\{ORCHESTRATOR_CONTEXT\}/); + assert.match(orchestratorPrompt, /"handoff_context"/); + assert.match(orchestratorPrompt, /ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT/); + assert.match(orchestratorPrompt, /ORCHESTRATOR_SELF_APPROVE_ENABLED/); + assert.match(orchestratorPrompt, /ORCHESTRATOR_SELF_MERGE_ENABLED/); + assert.match(orchestratorPrompt, /"user_message"/); + assert.match(orchestratorPrompt, /"clarification_request"/); + assert.match(orchestratorPrompt, /prior child finished with an open, unmerged PR/); + assert.match(runSource, /"ORCHESTRATOR_CONTEXT"/); + assert.match(runSource, /"ORCHESTRATOR_SELF_APPROVE_ENABLED"/); + assert.match(runSource, /"ORCHESTRATOR_SELF_MERGE_ENABLED"/); + assert.match(orchestratorDoc, /Implement --> Review: success \+ PR created/); + assert.match(orchestratorDoc, /continues sequential child implementation work/); + assert.match(orchestratorDoc, /workflow_dispatch/); + assert.match(orchestratorDoc, /handoff_context/); + assert.match(orchestratorDoc, /source handoff context/); + assert.match(orchestratorDoc, /Task for fix-pr/); + assert.match(orchestratorDoc, /agent\s+handle/); + assert.match(orchestratorDoc, /minimizes older visible handoff marker comments/); +}); + +test("orchestrator source handoff context is renderable in planner prompts", () => { + const runSource = readRepoFile(".agent/src/run.ts"); + const orchestratorPrompt = readRepoFile(".github/prompts/agent-orchestrator.md"); + const sourceContextName = "ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT"; + + assert.match(orchestratorPrompt, /\$\{ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT\}/); + assert.ok( + readSupplementalPromptVarNames(runSource).has(sourceContextName), + `${sourceContextName} must be allowlisted for runtime prompt rendering`, + ); +}); + +test("workflow docs cover hosted auth and self-hosting paths", () => { + const setupGuide = readRepoFile(".agent/docs/deployment/setup-guide.md"); + const selfHostedRunner = readRepoFile( + ".agent/docs/deployment/self-hosted-github-action-runner.md", + ); + + assert.match(setupGuide, /Official Sepo-hosted app/); + assert.match(setupGuide, /selected-repository Sepo GitHub App installation/); + assert.match(setupGuide, /App installed on the selected repository/); + assert.match( + setupGuide, + /do not need repo-local `AGENT_APP_ID` \/ `AGENT_APP_PRIVATE_KEY`\s+secrets/, + ); + assert.doesNotMatch(setupGuide, /AGENT_OIDC_EXCHANGE_URL/); + assert.doesNotMatch(setupGuide, /AGENT_OIDC_AUDIENCE/); + assert.match(setupGuide, /Bring your own GitHub App/); + assert.match(setupGuide, /`AGENT_PAT`/); + assert.match(setupGuide, /Contents:\*\* read and write/); + assert.match(setupGuide, /### Auth priority/); + assert.match( + setupGuide, + /1\. direct GitHub App token[\s\S]*2\. official OIDC broker exchange[\s\S]*3\. `AGENT_PAT`[\s\S]*4\. fallback workflow token `github\.token`/, + ); + assert.match(setupGuide, /fallback workflow token `github\.token`/i); + assert.doesNotMatch(setupGuide, /"oidc_token"/); + assert.match(selfHostedRunner, /infrastructure you operate/); + assert.match(selfHostedRunner, /`git`, `gh`, `jq`, `curl`, `bash`, and network/); +}); + +test("buildEnvelope produces a valid envelope with all fields", () => { + const envelope = buildEnvelope(VALID_PARAMS); + + assert.equal(envelope.schema_version, SCHEMA_VERSION); + assert.equal(envelope.repo_slug, "self-evolving/repo"); + assert.equal(envelope.route, "review"); + assert.equal(envelope.source_kind, "issue_comment"); + assert.equal(envelope.target_kind, "pull_request"); + assert.equal(envelope.target_number, 42); + assert.equal(envelope.target_url, "https://github.com/self-evolving/repo/pull/42"); + assert.equal(envelope.request_text, "please review this"); + assert.equal(envelope.requested_by, "lolipopshock"); + assert.equal(envelope.approval_comment_url, null); + assert.equal(envelope.lane, "default"); + assert.equal(envelope.thread_key, "self-evolving/repo:pull_request:42:review:default"); +}); + +test("buildEnvelope uses the default lane when lane is not provided", () => { + const envelope = buildEnvelope(VALID_PARAMS); + assert.equal(envelope.lane, "default"); +}); + +test("buildEnvelope respects explicit lane", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, lane: "portal" }); + assert.equal(envelope.lane, "portal"); + assert.equal(envelope.thread_key, "self-evolving/repo:pull_request:42:review:portal"); +}); + +test("buildEnvelope sets workflow when provided", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, workflow: "agent-review.yml" }); + assert.equal(envelope.workflow, "agent-review.yml"); +}); + +test("buildEnvelope preserves approval_comment_url", () => { + const url = "https://github.com/self-evolving/repo/issues/21#issuecomment-123"; + const envelope = buildEnvelope({ ...VALID_PARAMS, approval_comment_url: url }); + assert.equal(envelope.approval_comment_url, url); +}); + +test("validateEnvelope passes for a valid envelope", () => { + const envelope = buildEnvelope(VALID_PARAMS); + const errors = validateEnvelope(envelope); + assert.deepEqual(errors, []); +}); + +test("validateEnvelope catches missing required fields", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, repo_slug: "", target_number: 0 }); + const errors = validateEnvelope(envelope); + assert.ok(errors.some((error) => error.includes("repo_slug"))); + assert.ok(errors.some((error) => error.includes("target_number"))); +}); + +test("validateEnvelope catches invalid route", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, route: "deploy" }); + const errors = validateEnvelope(envelope); + assert.ok(errors.some((error) => error.includes("Invalid route"))); +}); + +test("validateEnvelope accepts dispatch, action, self-approval, and rubrics routes", () => { + for (const route of [ + "dispatch", + "create-action", + "agent-self-approve", + "agent-self-merge", + "rubrics-review", + "rubrics-initialization", + "rubrics-update", + ]) { + const envelope = buildEnvelope({ ...VALID_PARAMS, route }); + const errors = validateEnvelope(envelope); + assert.deepEqual(errors, []); + } +}); + +test("validateEnvelope catches invalid source_kind", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, source_kind: "webhook" }); + const errors = validateEnvelope(envelope); + assert.ok(errors.some((error) => error.includes("Invalid source_kind"))); +}); + +test("validateEnvelope catches invalid target_kind", () => { + const envelope = buildEnvelope({ ...VALID_PARAMS, target_kind: "commit" }); + const errors = validateEnvelope(envelope); + assert.ok(errors.some((error) => error.includes("Invalid target_kind"))); +}); + +test("buildThreadKey is deterministic", () => { + assert.equal( + buildThreadKey({ + repo_slug: "self-evolving/repo", + target_kind: "issue", + target_number: 21, + route: "implement", + }), + "self-evolving/repo:issue:21:implement:default", + ); +}); + +test("buildEnvelopeFromEventContext maps event context into an envelope", () => { + const envelope = buildEnvelopeFromEventContext( + { + body: "please implement", + sourceKind: "issue_comment", + targetKind: "issue", + targetNumber: "21", + targetUrl: "https://github.com/self-evolving/repo/issues/21", + }, + { + repo_slug: "self-evolving/repo", + route: "implement", + requested_by: "alice", + workflow: "agent-implement.yml", + lane: "default", + }, + ); + + assert.equal(envelope.target_number, 21); + assert.equal(envelope.request_text, "please implement"); + assert.equal(envelope.requested_by, "alice"); + assert.equal(envelope.workflow, "agent-implement.yml"); +}); + +test("envelopeToPromptVars exposes the prompt contract", () => { + const envelope = buildEnvelope(VALID_PARAMS); + assert.deepEqual(envelopeToPromptVars(envelope), { + REPO_SLUG: "self-evolving/repo", + ROUTE: "review", + SOURCE_KIND: "issue_comment", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + TARGET_URL: "https://github.com/self-evolving/repo/pull/42", + REQUEST_TEXT: "please review this", + MENTION_BODY: "please review this", + REQUESTED_BY: "lolipopshock", + WORKFLOW: "", + LANE: "default", + THREAD_KEY: "self-evolving/repo:pull_request:42:review:default", + }); +}); + +test("repository target kind accepts target_number=0", () => { + const envelope = buildEnvelope({ + ...VALID_PARAMS, + source_kind: "workflow_dispatch", + target_kind: "repository", + target_number: 0, + target_url: "https://github.com/self-evolving/repo", + }); + assert.deepEqual(validateEnvelope(envelope), []); +}); + +test("non-repository target kinds still require target_number", () => { + const envelope = buildEnvelope({ + ...VALID_PARAMS, + target_number: 0, + }); + const errors = validateEnvelope(envelope); + assert.ok(errors.some((e) => /target_number/.test(e))); +}); + +test("run-agent-task resolves memory mode from policy and threads memory env to the agent", () => { + const action = readRepoFile(".github/actions/run-agent-task/action.yml"); + const commitCli = readRepoFile(".agent/src/cli/commit.ts"); + assert.match(action, /memory_policy:/); + assert.match(action, /memory_mode_override:/); + assert.match(action, /memory_ref:/); + assert.doesNotMatch(action, /memory_bootstrap_if_missing:/); + assert.doesNotMatch(action, /memory_repository:/); + assert.doesNotMatch(action, /memory_path:/); + assert.doesNotMatch(action, /memory_commit_message:/); + assert.match(action, /AGENT_MEMORY_POLICY:\s*\$\{\{\s*inputs\.memory_policy\s*\}\}/); + assert.doesNotMatch(action, /vars\.AGENT_MEMORY_POLICY/); + assert.match(action, /cli\/memory\/resolve-policy\.js/); + assert.match(action, /steps\.memory_mode\.outputs\.read_enabled == 'true'/); + assert.match(action, /steps\.memory_mode\.outputs\.write_enabled == 'true'/); + // Commit must be gated on a clean agent exit, not just always(). + assert.match(action, /steps\.run\.outputs\.exit_code == '0'/); + assert.match(action, /Set up agent memory/); + assert.match(action, /MEMORY_AVAILABLE:\s*\$\{\{\s*steps\.memory\.outputs\.memory_available\s*\}\}/); + assert.match(action, /MEMORY_DIR:\s*\$\{\{\s*steps\.memory\.outputs\.memory_dir\s*\}\}/); + assert.match(action, /MEMORY_REF:\s*\$\{\{\s*steps\.memory\.outputs\.memory_ref\s*\}\}/); + assert.doesNotMatch(action, /PROMPT_VAR_MEMORY_/); + assert.match(action, /Commit memory edits/); + assert.match(action, /COMMIT_CWD:\s*\$\{\{\s*steps\.memory\.outputs\.memory_dir\s*\}\}/); + assert.doesNotMatch(action, /GITHUB_WORKSPACE:\s*\$\{\{\s*steps\.memory\.outputs\.memory_dir\s*\}\}/); + assert.match( + action, + /bootstrap_if_missing:\s*\$\{\{\s*inputs\.memory_mode_override == 'enabled' && 'true' \|\| 'false'\s*\}\}/, + ); + assert.match(action, /Report memory commit failure/); + assert.match(action, /steps\.commit_memory\.outcome == 'failure'/); + assert.match(action, /::warning title=Memory commit failed::/); + assert.match(action, /\.\/\.github\/actions\/download-agent-memory/); + assert.match(commitCli, /process\.env\.COMMIT_CWD \|\| process\.env\.GITHUB_WORKSPACE/); +}); + +test("run-agent-task only bootstraps missing rubrics for first-run initialization", () => { + const action = readRepoFile(".github/actions/run-agent-task/action.yml"); + const rubricsPrompt = readRepoFile(".github/prompts/_rubrics.md"); + + assert.match( + action, + /bootstrap_if_missing:\s*\$\{\{\s*inputs\.route == 'rubrics-initialization' && inputs\.rubrics_mode_override == 'enabled' && 'true' \|\| 'false'\s*\}\}/, + ); + assert.match(action, /Require rubric initialization commit/); + assert.match(action, /Rubrics initialization did not persist/); + assert.match(action, /Report rubrics validation failure/); + assert.match(action, /steps\.validate_rubrics\.outcome == 'failure'/); + assert.match(action, /::warning title=Rubrics validation failed::/); + assert.match(action, /RUBRICS_SELECT_ALL_ROUTES:\s*\$\{\{\s*inputs\.route == 'rubrics-review' && 'true' \|\| 'false'\s*\}\}/); + assert.match(action, /RUBRICS_LIMIT:\s*\$\{\{\s*inputs\.route == 'rubrics-review' && 'all' \|\| inputs\.rubrics_limit\s*\}\}/); + assert.match(action, /all_route_args\+=\(--all-routes\)/); + assert.match(action, /"\$\{all_route_args\[@\]\}"/); + assert.match(rubricsPrompt, /Agent \/ Rubrics \/ Initialization and Agent \/ Rubrics \/ Update/); +}); + +test("normal workflows honor rubrics policy instead of forcing read-only", () => { + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + const rubricsReviewWorkflow = readRepoFile(".github/workflows/agent-rubrics-review.yml"); + const rubricsInitializationWorkflow = readRepoFile(".github/workflows/agent-rubrics-initialization.yml"); + const rubricsInitializationPrompt = readRepoFile(".github/prompts/rubrics-initialization.md"); + const rubricsUpdateWorkflow = readRepoFile(".github/workflows/agent-rubrics-update.yml"); + const rubricsUpdatePrompt = readRepoFile(".github/prompts/rubrics-update.md"); + + for (const workflow of [implementWorkflow, fixPrWorkflow, reviewWorkflow, rubricsReviewWorkflow]) { + assert.doesNotMatch(workflow, /rubrics_mode_override:\s*'read-only'/); + assert.match(workflow, /rubrics_policy:\s*\$\{\{\s*vars\.AGENT_RUBRICS_POLICY \|\| ''\s*\}\}/); + } + assert.match(rubricsInitializationWorkflow, /rubrics_mode_override:\s*'enabled'/); + assert.match(rubricsUpdateWorkflow, /rubrics_mode_override:\s*'enabled'/); + assert.match(rubricsInitializationPrompt, /gh repo view \$\{REPO_SLUG\} --json owner,nameWithOwner/); + assert.match(rubricsInitializationPrompt, /permissions\.admin or \.permissions\.maintain/); + assert.match(rubricsInitializationPrompt, /primary source of user\/team preference/); + assert.match(rubricsUpdatePrompt, /author's login,[\s\S]*user type,[\s\S]*author_association/); + assert.match(rubricsUpdatePrompt, /gh repo view \$\{REPO_SLUG\} --json owner,nameWithOwner/); + assert.match(rubricsUpdatePrompt, /permissions\.admin or \.permissions\.maintain/); + assert.match(rubricsUpdatePrompt, /non-primary maintainer comments as corroborating evidence/); + assert.match(rubricsUpdatePrompt, /automatic merged-PR rubrics-update runs[\s\S]*closed\/merged/); + assert.match(rubricsUpdatePrompt, /authored by `REQUESTED_BY`; it does not make other PR conversation[\s\S]*participants trusted/); + assert.match(rubricsUpdateWorkflow, /issues:\s*write/); + assert.match(rubricsUpdateWorkflow, /id:\s*rubrics_update/); + assert.match(rubricsUpdateWorkflow, /Prepare rubrics update summary/); + assert.match(rubricsUpdateWorkflow, /prepare-rubrics-update-summary\.js/); + assert.match(rubricsUpdateWorkflow, /Post rubrics update summary/); +}); + +test("rubrics-review prompt chooses from full active rubric context", () => { + const rubricsReviewPrompt = readRepoFile(".github/prompts/rubrics-review.md"); + + assert.match(rubricsReviewPrompt, /full active rubric set/); + assert.match(rubricsReviewPrompt, /do not score unrelated route\/process rubrics/); +}); + +test("memory workflows exist and point at the right CLIs / prompts", () => { + const bootstrapWorkflow = readRepoFile(".github/workflows/agent-memory-bootstrap.yml"); + const syncWorkflow = readRepoFile(".github/workflows/agent-memory-sync.yml"); + const prClosedWorkflow = readRepoFile(".github/workflows/agent-memory-pr-closed.yml"); + const scanWorkflow = readRepoFile(".github/workflows/agent-memory-scan.yml"); + + assert.match(bootstrapWorkflow, /^name: Agent \/ Memory \/ Initialization$/m); + assert.match(syncWorkflow, /^name: Agent \/ Memory \/ Sync GitHub Artifacts$/m); + assert.match(prClosedWorkflow, /^name: Agent \/ Memory \/ Record PR Closure$/m); + assert.match(scanWorkflow, /^name: Agent \/ Memory \/ Curate Recent Activity$/m); + assert.match(bootstrapWorkflow, /workflow_dispatch:/); + assert.match(bootstrapWorkflow, /inputs:\s*[\s\S]*memory_ref:/); + assert.match(bootstrapWorkflow, /git\/matching-refs\/heads\/\$\{MEMORY_REF\}/); + assert.match(bootstrapWorkflow, /exact_ref="refs\/heads\/\$\{MEMORY_REF\}"/); + assert.match(bootstrapWorkflow, /grep -Fxq "\$exact_ref"/); + assert.match(bootstrapWorkflow, /already exists\. Bootstrap is first-run only\./); + assert.match(bootstrapWorkflow, /uses: \.\/\.github\/actions\/download-agent-memory/); + assert.match(bootstrapWorkflow, /bootstrap_if_missing: "true"/); + assert.match(bootstrapWorkflow, /Resolve memory bootstrap provider/); + assert.match(bootstrapWorkflow, /install_codex:\s*\$\{\{\s*steps\.provider\.outputs\.install_codex\s*\}\}/); + assert.match(bootstrapWorkflow, /install_claude:\s*\$\{\{\s*steps\.provider\.outputs\.install_claude\s*\}\}/); + assert.match(bootstrapWorkflow, /node \.agent\/dist\/cli\/memory\/read-sync-state\.js/); + assert.match(bootstrapWorkflow, /node \.agent\/dist\/cli\/memory\/sync-github-artifacts\.js/); + assert.match(bootstrapWorkflow, /node \.agent\/dist\/cli\/memory\/write-sync-state\.js/); + assert.match(bootstrapWorkflow, /PREVIOUS_LAST_SYNC: ""/); + assert.doesNotMatch(bootstrapWorkflow, /steps\.commit\.outputs\.committed == 'true'/); + assert.match(bootstrapWorkflow, /steps\.memory\.outputs\.memory_available == 'true'/); + assert.match(bootstrapWorkflow, /node \$\{\{ github\.workspace \}\}\/\.agent\/dist\/cli\/commit\.js/); + assert.match(bootstrapWorkflow, /COMMIT_CWD:\s*\$\{\{\s*runner\.temp\s*\}\}\/agent-memory/); + assert.doesNotMatch(bootstrapWorkflow, /GITHUB_WORKSPACE:\s*\$\{\{\s*runner\.temp\s*\}\}\/agent-memory/); + assert.match(bootstrapWorkflow, /COMMIT_MESSAGE: "chore\(memory\): initialize memory branch"/); + assert.match(bootstrapWorkflow, /COMMIT_MESSAGE: "chore\(memory\): sync github artifacts"/); + assert.match(bootstrapWorkflow, /permission_mode: approve-all/); + assert.match(bootstrapWorkflow, /prompt: memory-scan/); + assert.match(bootstrapWorkflow, /memory_mode_override: 'enabled'/); + assert.match(bootstrapWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + assert.match(bootstrapWorkflow, /workflow: agent-memory-bootstrap\.yml/); + assert.match(bootstrapWorkflow, /inputs\.memory_ref \|\| vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'/); + assert.doesNotMatch(bootstrapWorkflow, /dispatch-workflow\.js/); + assert.match(syncWorkflow, /cron: "17 \*\/6 \* \* \*"/); + assert.match(syncWorkflow, /node \.agent\/dist\/cli\/memory\/read-sync-state\.js/); + assert.match(syncWorkflow, /node \.agent\/dist\/cli\/memory\/sync-github-artifacts\.js/); + assert.match(syncWorkflow, /node \.agent\/dist\/cli\/memory\/write-sync-state\.js/); + assert.match(syncWorkflow, /inputs\.memory_ref \|\| vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'/); + assert.match(syncWorkflow, /GH_TOKEN:\s*\$\{\{\s*steps\.auth\.outputs\.token\s*\}\}/); + assert.match(syncWorkflow, /GITHUB_TOKEN:\s*\$\{\{\s*steps\.auth\.outputs\.token\s*\}\}/); + assert.match(syncWorkflow, /MEMORY_SYNC_LOOKBACK_DAYS:\s*\$\{\{\s*inputs\.lookback_days \|\| '30'\s*\}\}/); + assert.match(syncWorkflow, /bootstrap_if_missing: "true"/); + assert.match(syncWorkflow, /COMMIT_CWD:\s*\$\{\{\s*runner\.temp\s*\}\}\/agent-memory/); + assert.doesNotMatch(syncWorkflow, /GITHUB_WORKSPACE:\s*\$\{\{\s*runner\.temp\s*\}\}\/agent-memory/); + assert.doesNotMatch(syncWorkflow, /dispatch_scan_on_success:/); + assert.doesNotMatch(syncWorkflow, /dispatch-workflow\.js/); + assert.doesNotMatch(syncWorkflow, /Bootstrap memory checkout/); + assert.doesNotMatch(syncWorkflow, /date -u -d/); + + // The dedicated memory scaffolds bypass the memory policy so they always run. + assert.match(prClosedWorkflow, /pull_request_target:\s*[\s\S]*types: \[closed\]/); + assert.match(prClosedWorkflow, /permission_mode: approve-all/); + assert.match(prClosedWorkflow, /prompt: memory-pr-closed/); + assert.match(prClosedWorkflow, /memory_mode_override: 'enabled'/); + assert.match(prClosedWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + assert.doesNotMatch(prClosedWorkflow, /memory_bootstrap_if_missing:/); + assert.match(prClosedWorkflow, /inputs\.memory_ref \|\| vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'/); + assert.doesNotMatch(prClosedWorkflow, /continue-on-error:\s*true/); + // Fork safety: either same repo, workflow_dispatch, or merged fork PR. + assert.match(prClosedWorkflow, /github\.event\.pull_request\.head\.repo\.full_name == github\.repository/); + assert.match(prClosedWorkflow, /github\.event\.pull_request\.merged == true/); + + assert.match(scanWorkflow, /cron: '0 \*\/6 \* \* \*'/); + assert.match(scanWorkflow, /permission_mode: approve-all/); + assert.match(scanWorkflow, /prompt: memory-scan/); + assert.match(scanWorkflow, /memory_mode_override: 'enabled'/); + assert.match(scanWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + assert.doesNotMatch(scanWorkflow, /memory_bootstrap_if_missing:/); + assert.match(scanWorkflow, /inputs\.memory_ref \|\| vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'/); + assert.match(scanWorkflow, /target_kind: repository/); + assert.doesNotMatch(scanWorkflow, /continue-on-error:\s*true/); +}); + +test("download-agent-memory only suppresses missing-branch failures", () => { + const action = readRepoFile(".github/actions/download-agent-memory/action.yml"); + + assert.match(action, /bootstrap_if_missing:/); + assert.match(action, /git clone --depth=1 --branch "\$ref" --single-branch "\$auth_url" "\$dest"/); + assert.match( + action, + /if git ls-remote --exit-code --heads "\$auth_url" "\$ref"[\s\S]*else[\s\S]*lsremote_status=\$\?[\s\S]*fi/, + ); + assert.match(action, /if \[ "\$lsremote_status" -eq 2 \]/); + assert.match(action, /if \[ "\$INPUT_BOOTSTRAP_IF_MISSING" = "true" \]/); + assert.match(action, /memory\/init\.js/); + assert.match(action, /Failed to clone memory branch/); +}); + +test("main execution workflows rely on the default memory policy (no explicit override)", () => { + const routerWorkflow = readRepoFile(".github/workflows/agent-router.yml"); + const implementWorkflow = readRepoFile(".github/workflows/agent-implement.yml"); + const fixPrWorkflow = readRepoFile(".github/workflows/agent-fix-pr.yml"); + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + + // No explicit memory_enabled flag — memory is on by default via policy. + assert.doesNotMatch(routerWorkflow, /memory_enabled:/); + assert.doesNotMatch(implementWorkflow, /memory_enabled:/); + assert.doesNotMatch(fixPrWorkflow, /memory_enabled:/); + assert.match(routerWorkflow, /memory_ref:\s*\$\{\{\s*vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'\s*\}\}/); + assert.match(implementWorkflow, /memory_ref:\s*\$\{\{\s*vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'\s*\}\}/); + assert.match(fixPrWorkflow, /memory_ref:\s*\$\{\{\s*vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'\s*\}\}/); + assert.match(routerWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + assert.match(implementWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + assert.match(fixPrWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); + + // Review matrix is explicitly read-only so the parallel claude+codex jobs + // don't race to push to agent/memory; synthesize (no override) inherits + // the default mode and writes. + assert.match(reviewWorkflow, /memory_mode_override: 'read-only'/); + assert.match(reviewWorkflow, /memory_ref:\s*\$\{\{\s*vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'\s*\}\}/); + assert.match(reviewWorkflow, /memory_policy:\s*\$\{\{\s*vars\.AGENT_MEMORY_POLICY \|\| ''\s*\}\}/); +}); + +test("agent-review permissions are scoped per-job: reviewers read-only, synthesize writes", () => { + const reviewWorkflow = readRepoFile(".github/workflows/agent-review.yml"); + + // Top-level workflow permissions keep contents read-only; actions write + // allows the synthesize job to dispatch automation handoffs. + assert.match(reviewWorkflow, /^permissions:\s*\n\s+actions: write\s*\n\s+contents: read/m); + + // Reviewer job keeps contents:read. + assert.match( + reviewWorkflow, + /review:\s*\n\s+# Ordering-only:[\s\S]*?needs: \[prepare\]\s*\n\s+if: \$\{\{ !cancelled\(\) \}\}\s*\n\s+# Reviewer lanes are best-effort[\s\S]*?permissions:\s*\n\s+# Reviewer jobs stay read-only[\s\S]*?contents: read/, + ); + + // Synthesize job upgrades to contents:write for the memory commit. + assert.match( + reviewWorkflow, + /synthesize:\s*\n\s+needs: \[prepare, review\]\s*\n\s+if: \$\{\{ !cancelled\(\) \}\}\s*\n\s+permissions:[\s\S]*?contents: write/, + ); +}); + +test("branch cleanup preserves shared agent branches", () => { + const cleanup = readRepoFile(".github/workflows/agent-branch-cleanup.yml"); + assert.match(cleanup, /head\.ref != \(vars\.AGENT_MEMORY_REF \|\| 'agent\/memory'\)/); + assert.match(cleanup, /head\.ref != \(vars\.AGENT_RUBRICS_REF \|\| 'agent\/rubrics'\)/); +}); + +test("branch cleanup retargets stacked PRs before deleting merged branches", () => { + const cleanup = readRepoFile(".github/workflows/agent-branch-cleanup.yml"); + assert.match(cleanup, /^permissions:\s*\n\s+contents: write\s*\n\s+pull-requests: write/m); + assert.match(cleanup, /const retargetBase = context\.payload\.pull_request\?\.base\?\.ref/); + assert.match(cleanup, /github\.paginate\(github\.rest\.pulls\.list[\s\S]*base: branch/); + assert.match(cleanup, /github\.rest\.pulls\.update[\s\S]*base: retargetBase/); + + const retargetIndex = cleanup.indexOf("github.rest.pulls.update"); + const deleteIndex = cleanup.indexOf("github.rest.git.deleteRef"); + assert.notEqual(retargetIndex, -1); + assert.notEqual(deleteIndex, -1); + assert.ok(retargetIndex < deleteIndex); +}); + +test("branch cleanup preserves merged branch when dependent PR retarget fails", async () => { + const calls: string[] = []; + const retargetError = new Error("retarget failed"); + + const pullsList = async (): Promise => []; + const github = { + paginate: async (endpoint: unknown, options: Record) => { + calls.push("pulls.list"); + assert.equal(endpoint, pullsList); + assert.deepEqual(options, { + owner: "self-evolving", + repo: "repo", + state: "open", + base: "agent/implement-issue-122/codex-25293354687", + per_page: 100, + }); + return [{ number: 116 }]; + }, + rest: { + pulls: { + list: pullsList, + update: async (options: Record) => { + calls.push(`pulls.update:${String(options.pull_number)}`); + assert.deepEqual(options, { + owner: "self-evolving", + repo: "repo", + pull_number: 116, + base: "main", + }); + throw retargetError; + }, + }, + git: { + deleteRef: async () => { + calls.push("git.deleteRef"); + }, + }, + }, + }; + const context = { + repo: { owner: "self-evolving", repo: "repo" }, + payload: { + pull_request: { + head: { ref: "agent/implement-issue-122/codex-25293354687" }, + base: { ref: "main" }, + }, + }, + }; + const core = { + info: () => {}, + setFailed: (message: string) => { + calls.push(`core.setFailed:${message}`); + }, + }; + + await assert.rejects(runBranchCleanupScript({ github, context, core }), retargetError); + assert.deepEqual(calls, ["pulls.list", "pulls.update:116"]); +}); + +test("memory and rubric guidance live in dedicated conditional prompt fragments", () => { + const base = readRepoFile(".github/prompts/_base.md"); + const memory = readRepoFile(".github/prompts/_memory.md"); + const rubrics = readRepoFile(".github/prompts/_rubrics.md"); + const runSource = readRepoFile(".agent/src/run.ts"); + + assert.doesNotMatch(base, /Repository memory/); + assert.doesNotMatch(base, /memory\/search\.js/); + assert.doesNotMatch(base, /memory\/update\.js/); + assert.doesNotMatch(base, /MEMORY_AVAILABLE/); + assert.match(memory, /Repository memory/); + assert.match(memory, /memory\/search\.js/); + assert.match(memory, /memory\/update\.js/); + assert.match(memory, /\$\{MEMORY_DIR\}/); + assert.match(runSource, /MEMORY_PROMPT_PATH = "\.github\/prompts\/_memory\.md"/); + assert.match(runSource, /vars\.MEMORY_AVAILABLE === "true"/); + assert.match(rubrics, /User\/team rubrics/); + assert.match(rubrics, /\$\{RUBRICS_CONTEXT\}/); + assert.match(runSource, /RUBRICS_PROMPT_PATH = "\.github\/prompts\/_rubrics\.md"/); + assert.match(runSource, /vars\.RUBRICS_AVAILABLE === "true"/); + assert.match(runSource, /base \+ memory \+ rubrics \+ template/); +}); diff --git a/.agent/src/__tests__/extract-context-cli.test.ts b/.agent/src/__tests__/extract-context-cli.test.ts new file mode 100644 index 0000000..0d94944 --- /dev/null +++ b/.agent/src/__tests__/extract-context-cli.test.ts @@ -0,0 +1,1138 @@ +import { execFileSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + + return outputs; +} + +interface ExtractContextCliOptions { + eventName: string; + payload: Record; + env?: NodeJS.ProcessEnv; + ghScript?: string; +} + +function runExtractContextCli(options: ExtractContextCliOptions): Map { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + writeFileSync(eventPath, JSON.stringify(options.payload), "utf8"); + writeFileSync(outputPath, "", "utf8"); + + if (options.ghScript) { + writeFileSync(join(tempDir, "gh"), options.ghScript, { + encoding: "utf8", + mode: 0o755, + }); + } + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + ...(options.ghScript ? { PATH: `${tempDir}:${process.env.PATH || ""}` } : {}), + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: options.eventName, + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + ...options.env, + }, + stdio: "pipe", + }); + + return parseGithubOutput(outputPath); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +} + +test("extract-context skips approval commands for a configured custom mention", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + comment: { + id: 99, + node_id: "IC_99", + html_url: "https://github.com/self-evolving/repo/pull/119#issuecomment-99", + body: "@custom/agent /approve req-a1b2c3", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + issue: { + number: 119, + html_url: "https://github.com/self-evolving/repo/pull/119", + pull_request: { url: "https://api.github.com/repos/self-evolving/repo/pulls/119" }, + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@custom/agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "false"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context refreshes issue author association from the GitHub API", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + issue: { + number: 2, + title: "Investigate auth", + body: "@sepo-agent can you investigate?", + html_url: "https://github.com/self-evolving/repo/issues/2", + node_id: "I_2", + author_association: "NONE", + user: { login: "alice" }, + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/issues/2\" ]; then\n printf 'MEMBER\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "MEMBER"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context refreshes contributor issue author association from the GitHub API", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + issue: { + number: 5, + title: "Investigate auth", + body: "@sepo-agent /answer can you investigate?", + html_url: "https://github.com/self-evolving/repo/issues/5", + node_id: "I_5", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/issues/5\" ]; then\n printf 'MEMBER\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "MEMBER"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context promotes weak issue author association for repository collaborators", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + issue: { + number: 7, + title: "Investigate auth", + body: "@sepo-agent /answer can you investigate?", + html_url: "https://github.com/self-evolving/repo/issues/7", + node_id: "I_7", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + [ + "#!/usr/bin/env bash", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/issues/7\" ]; then", + " printf 'CONTRIBUTOR\\n'", + " exit 0", + "fi", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/collaborators/alice\" ]; then", + " exit 0", + "fi", + "printf 'unexpected gh args: %s\\n' \"$*\" >&2", + "exit 1", + "", + ].join("\n"), + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "COLLABORATOR"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +const collaboratorGhScript = [ + "#!/usr/bin/env bash", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/collaborators/alice\" ]; then", + " exit 0", + "fi", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"graphql\" ]; then", + " printf '{\"data\":{\"node\":{\"replyTo\":null}}}\\n'", + " exit 0", + "fi", + "printf 'unexpected gh args: %s\\n' \"$*\" >&2", + "exit 1", + "", +].join("\n"); + +const weakMentionCollaboratorCases: Array<{ + name: string; + eventName: string; + expectedSourceKind: string; + payload: Record; +}> = [ + { + name: "issue comment", + eventName: "issue_comment", + expectedSourceKind: "issue_comment", + payload: { + sender: { login: "alice", type: "User" }, + comment: { + id: 201, + node_id: "IC_201", + html_url: "https://github.com/self-evolving/repo/issues/201#issuecomment-201", + body: "@sepo-agent /answer please check this", + author_association: "NONE", + user: { login: "alice" }, + }, + issue: { + number: 201, + html_url: "https://github.com/self-evolving/repo/issues/201", + }, + }, + }, + { + name: "discussion comment", + eventName: "discussion_comment", + expectedSourceKind: "discussion_comment", + payload: { + sender: { login: "alice", type: "User" }, + comment: { + id: 202, + node_id: "DC_202", + html_url: "https://github.com/self-evolving/repo/discussions/202#discussioncomment-202", + body: "@sepo-agent /answer please check this", + authorAssociation: "CONTRIBUTOR", + user: { login: "alice" }, + }, + discussion: { + number: 202, + html_url: "https://github.com/self-evolving/repo/discussions/202", + node_id: "D_202", + }, + }, + }, + { + name: "discussion", + eventName: "discussion", + expectedSourceKind: "discussion", + payload: { + sender: { login: "alice", type: "User" }, + discussion: { + number: 205, + title: "Investigate auth", + body: "@sepo-agent /answer please check this", + html_url: "https://github.com/self-evolving/repo/discussions/205", + node_id: "D_205", + authorAssociation: "NONE", + user: { login: "alice" }, + }, + }, + }, + { + name: "pull request review comment", + eventName: "pull_request_review_comment", + expectedSourceKind: "pull_request_review_comment", + payload: { + sender: { login: "alice", type: "User" }, + comment: { + id: 203, + node_id: "PRRC_203", + html_url: "https://github.com/self-evolving/repo/pull/203#discussion_r203", + body: "@sepo-agent /answer please check this", + author_association: "FIRST_TIMER", + user: { login: "alice" }, + }, + pull_request: { + number: 203, + html_url: "https://github.com/self-evolving/repo/pull/203", + }, + }, + }, + { + name: "pull request review", + eventName: "pull_request_review", + expectedSourceKind: "pull_request_review", + payload: { + sender: { login: "alice", type: "User" }, + review: { + id: 204, + node_id: "PRR_204", + html_url: "https://github.com/self-evolving/repo/pull/204#pullrequestreview-204", + body: "@sepo-agent /answer please check this", + author_association: "FIRST_TIME_CONTRIBUTOR", + user: { login: "alice" }, + }, + pull_request: { + number: 204, + html_url: "https://github.com/self-evolving/repo/pull/204", + }, + }, + }, +]; + +for (const testCase of weakMentionCollaboratorCases) { + test(`extract-context promotes weak ${testCase.name} associations for repository collaborators`, () => { + const outputs = runExtractContextCli({ + eventName: testCase.eventName, + payload: testCase.payload, + ghScript: collaboratorGhScript, + env: { + GITHUB_REPOSITORY: "self-evolving/repo", + }, + }); + + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "COLLABORATOR"); + assert.equal(outputs.get("source_kind"), testCase.expectedSourceKind); + assert.equal(outputs.get("requested_by"), "alice"); + assert.equal(outputs.get("requested_route"), "answer"); + }); +} + +const nonCollaboratorGhScript = [ + "#!/usr/bin/env bash", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/collaborators/alice\" ]; then", + " exit 1", + "fi", + "if [ \"$1\" = \"api\" ] && [ \"$2\" = \"graphql\" ]; then", + " printf '{\"data\":{\"node\":{\"replyTo\":null}}}\\n'", + " exit 0", + "fi", + "printf 'unexpected gh args: %s\\n' \"$*\" >&2", + "exit 1", + "", +].join("\n"); + +test("extract-context preserves weak discussion comment association when collaborator lookup fails", () => { + const outputs = runExtractContextCli({ + eventName: "discussion_comment", + payload: { + sender: { login: "alice", type: "User" }, + comment: { + id: 206, + node_id: "DC_206", + html_url: "https://github.com/self-evolving/repo/discussions/206#discussioncomment-206", + body: "@sepo-agent /answer please check this", + authorAssociation: "CONTRIBUTOR", + user: { login: "alice" }, + }, + discussion: { + number: 206, + html_url: "https://github.com/self-evolving/repo/discussions/206", + node_id: "D_206", + }, + }, + ghScript: nonCollaboratorGhScript, + env: { + GITHUB_REPOSITORY: "self-evolving/repo", + }, + }); + + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "CONTRIBUTOR"); + assert.equal(outputs.get("source_kind"), "discussion_comment"); + assert.equal(outputs.get("requested_by"), "alice"); + assert.equal(outputs.get("requested_route"), "answer"); +}); + +test("extract-context preserves contributor association when refreshed issue association matches", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + issue: { + number: 6, + title: "Investigate auth", + body: "@sepo-agent /answer can you investigate?", + html_url: "https://github.com/self-evolving/repo/issues/6", + node_id: "I_6", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/issues/6\" ]; then\n printf 'CONTRIBUTOR\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "CONTRIBUTOR"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context resolves label actors as OWNER for personal repositories", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "labeled", + sender: { login: "alice", type: "User" }, + repository: { + private: true, + owner: { login: "alice", type: "User" }, + }, + issue: { + number: 7, + title: "Queue review", + body: "Run the review label", + html_url: "https://github.com/alice/agent/issues/7", + node_id: "I_7", + author_association: "NONE", + user: { login: "bob" }, + }, + label: { name: "agent/review" }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "alice/agent", + INPUT_TRIGGER_KIND: "label", + INPUT_LABEL_NAME: "agent/review", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "OWNER"); + assert.equal(outputs.get("requested_by"), "alice"); + assert.equal(outputs.get("requested_route"), "review"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context resolves label actors as MEMBER when org membership is visible", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "labeled", + sender: { login: "alice", type: "User" }, + repository: { + private: true, + owner: { login: "self-evolving", type: "Organization" }, + }, + issue: { + number: 8, + title: "Queue implement", + body: "Run the implementation label", + html_url: "https://github.com/self-evolving/repo/issues/8", + node_id: "I_8", + author_association: "NONE", + user: { login: "bob" }, + }, + label: { name: "agent/implement" }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"orgs/self-evolving/memberships/alice\" ]; then\n printf 'active\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_TRIGGER_KIND: "label", + INPUT_LABEL_NAME: "agent/implement", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "MEMBER"); + assert.equal(outputs.get("requested_route"), "implement"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context resolves label actors as COLLABORATOR from repository permission", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "labeled", + sender: { login: "alice", type: "User" }, + repository: { + private: true, + owner: { login: "self-evolving", type: "Organization" }, + }, + issue: { + number: 9, + title: "Queue answer", + body: "Run the answer label", + html_url: "https://github.com/self-evolving/repo/issues/9", + node_id: "I_9", + author_association: "NONE", + user: { login: "bob" }, + }, + label: { name: "agent/answer" }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"orgs/self-evolving/memberships/alice\" ]; then\n exit 1\nfi\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"orgs/self-evolving/members/alice\" ]; then\n exit 1\nfi\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/collaborators/alice/permission\" ]; then\n printf 'write\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_TRIGGER_KIND: "label", + INPUT_LABEL_NAME: "agent/answer", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "COLLABORATOR"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context does not treat none repository permission as collaborator", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "labeled", + sender: { login: "alice", type: "User" }, + repository: { + private: true, + owner: { login: "self-evolving", type: "Organization" }, + }, + issue: { + number: 10, + title: "Queue answer", + body: "Run the answer label", + html_url: "https://github.com/self-evolving/repo/issues/10", + node_id: "I_10", + author_association: "NONE", + user: { login: "bob" }, + }, + label: { name: "agent/answer" }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + "#!/usr/bin/env bash\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"orgs/self-evolving/memberships/alice\" ]; then\n exit 1\nfi\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"orgs/self-evolving/members/alice\" ]; then\n exit 1\nfi\nif [ \"$1\" = \"api\" ] && [ \"$2\" = \"repos/self-evolving/repo/collaborators/alice/permission\" ]; then\n printf 'none\\n'\n exit 0\nfi\nprintf 'unexpected gh args: %s\\n' \"$*\" >&2\nexit 1\n", + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issues", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_TRIGGER_KIND: "label", + INPUT_LABEL_NAME: "agent/answer", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "NONE"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context responds when an edited issue comment adds a mention", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "edited", + sender: { login: "alice", type: "User" }, + comment: { + id: 101, + node_id: "IC_101", + html_url: "https://github.com/self-evolving/repo/issues/164#issuecomment-101", + body: "please check @sepo-agent", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + changes: { + body: { + from: "please check", + }, + }, + issue: { + number: 164, + html_url: "https://github.com/self-evolving/repo/issues/164", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("source_kind"), "issue_comment"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context skips edited issue comments when mention was already present", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "edited", + sender: { login: "alice", type: "User" }, + comment: { + id: 102, + node_id: "IC_102", + html_url: "https://github.com/self-evolving/repo/issues/164#issuecomment-102", + body: "please check @sepo-agent again", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + changes: { + body: { + from: "please check @sepo-agent", + }, + }, + issue: { + number: 164, + html_url: "https://github.com/self-evolving/repo/issues/164", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "false"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context responds when an edited discussion comment adds a mention", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "edited", + sender: { login: "alice", type: "User" }, + comment: { + id: 103, + node_id: "DC_103", + html_url: "https://github.com/self-evolving/repo/discussions/164#discussioncomment-103", + body: "please check @sepo-agent", + authorAssociation: "CONTRIBUTOR", + user: { login: "alice" }, + }, + changes: { + body: { + from: "please check", + }, + }, + discussion: { + number: 164, + html_url: "https://github.com/self-evolving/repo/discussions/164", + node_id: "D_164", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "discussion_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("source_kind"), "discussion_comment"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context responds when an edited review comment adds a mention", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + action: "edited", + sender: { login: "alice", type: "User" }, + comment: { + id: 104, + node_id: "PRRC_104", + html_url: "https://github.com/self-evolving/repo/pull/168#discussion_r104", + body: "please check @sepo-agent", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + changes: { + body: { + from: "please check", + }, + }, + pull_request: { + number: 168, + html_url: "https://github.com/self-evolving/repo/pull/168", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "pull_request_review_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("source_kind"), "pull_request_review_comment"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context lets public contributor mentions reach dispatch triage", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + repository: { private: false }, + comment: { + id: 105, + node_id: "IC_105", + html_url: "https://github.com/self-evolving/repo/issues/170#issuecomment-105", + body: "please check @sepo-agent", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + issue: { + number: 170, + html_url: "https://github.com/self-evolving/repo/issues/170", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "CONTRIBUTOR"); + assert.equal(outputs.get("requested_route"), ""); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context preserves explicit routes for later policy checks", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + repository: { private: false }, + comment: { + id: 106, + node_id: "IC_106", + html_url: "https://github.com/self-evolving/repo/issues/171#issuecomment-106", + body: "@sepo-agent /answer please check this", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + issue: { + number: 171, + html_url: "https://github.com/self-evolving/repo/issues/171", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("extract-context keeps known associations available for later policy checks", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-extract-context-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + comment: { + id: 107, + node_id: "IC_107", + html_url: "https://github.com/self-evolving/repo/issues/172#issuecomment-107", + body: "@sepo-agent /answer please check this", + author_association: "NONE", + user: { login: "alice" }, + }, + issue: { + number: 172, + html_url: "https://github.com/self-evolving/repo/issues/172", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/extract-context.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + INPUT_MENTION: "@sepo-agent", + INPUT_TRIGGER_KIND: "mention", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_respond"), "true"); + assert.equal(outputs.get("association"), "NONE"); + assert.equal(outputs.get("requested_route"), "answer"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/fetch-discussion-transcript-cli.test.ts b/.agent/src/__tests__/fetch-discussion-transcript-cli.test.ts new file mode 100644 index 0000000..dcdb239 --- /dev/null +++ b/.agent/src/__tests__/fetch-discussion-transcript-cli.test.ts @@ -0,0 +1,162 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + parseDiscussionNumber, + resolveRepoSlug, + runFetchDiscussionTranscriptCli, +} from "../cli/fetch-discussion-transcript.js"; +import type { GraphQLClient } from "../github-graphql.js"; + +function createBufferWriter(): { + writer: { write(chunk: string): void }; + read(): string; +} { + let output = ""; + return { + writer: { + write(chunk: string) { + output += chunk; + }, + }, + read() { + return output; + }, + }; +} + +test("parseDiscussionNumber accepts positive integers only", () => { + assert.equal(parseDiscussionNumber("12"), 12); + assert.equal(parseDiscussionNumber("0"), null); + assert.equal(parseDiscussionNumber("-3"), null); + assert.equal(parseDiscussionNumber("abc"), null); + assert.equal(parseDiscussionNumber(undefined), null); +}); + +test("resolveRepoSlug prefers REPO_SLUG from env", () => { + let called = false; + const repoSlug = resolveRepoSlug({ + env: { REPO_SLUG: "self-evolving/repo" }, + execGh() { + called = true; + throw new Error("should not execute gh"); + }, + }); + + assert.equal(repoSlug, "self-evolving/repo"); + assert.equal(called, false); +}); + +test("resolveRepoSlug falls back to gh repo view", () => { + const repoSlug = resolveRepoSlug({ + env: {}, + execGh() { + return Buffer.from("self-evolving/repo\n", "utf8"); + }, + }); + + assert.equal(repoSlug, "self-evolving/repo"); +}); + +test("runFetchDiscussionTranscriptCli prints usage for missing or invalid numbers", () => { + const stdout = createBufferWriter(); + const stderr = createBufferWriter(); + + const exitCode = runFetchDiscussionTranscriptCli([], { + stdout: stdout.writer, + stderr: stderr.writer, + }); + + assert.equal(exitCode, 1); + assert.equal(stdout.read(), ""); + assert.match(stderr.read(), /Usage: fetch-discussion-transcript\.js/); +}); + +test("runFetchDiscussionTranscriptCli reports repository resolution failures", () => { + const stdout = createBufferWriter(); + const stderr = createBufferWriter(); + + const exitCode = runFetchDiscussionTranscriptCli(["12"], { + env: {}, + stdout: stdout.writer, + stderr: stderr.writer, + resolveRepoSlug() { + return ""; + }, + }); + + assert.equal(exitCode, 1); + assert.equal(stdout.read(), ""); + assert.match(stderr.read(), /Could not determine repository/); +}); + +test("runFetchDiscussionTranscriptCli renders the transcript on success", () => { + const stdout = createBufferWriter(); + const stderr = createBufferWriter(); + let receivedOwner = ""; + let receivedRepo = ""; + let receivedNumber = 0; + + const exitCode = runFetchDiscussionTranscriptCli(["12"], { + env: { REPO_SLUG: "self-evolving/repo" }, + stdout: stdout.writer, + stderr: stderr.writer, + createClient() { + return { + graphql(): T { + throw new Error("not used by test fetcher"); + }, + } satisfies GraphQLClient; + }, + fetchDiscussionTranscript(_client, owner, repo, number) { + receivedOwner = owner; + receivedRepo = repo; + receivedNumber = number; + return { + discussionMeta: { + id: "discussion-12", + title: "Title", + url: "https://github.com/self-evolving/repo/discussions/12", + body: "Body", + author: "alice", + }, + comments: [], + }; + }, + buildDiscussionTranscript(discussionMeta) { + return `Transcript for ${discussionMeta.title}\n`; + }, + }); + + assert.equal(exitCode, 0); + assert.equal(receivedOwner, "self-evolving"); + assert.equal(receivedRepo, "repo"); + assert.equal(receivedNumber, 12); + assert.equal(stdout.read(), "Transcript for Title\n"); + assert.equal(stderr.read(), ""); +}); + +test("runFetchDiscussionTranscriptCli reports fetch failures to stderr", () => { + const stdout = createBufferWriter(); + const stderr = createBufferWriter(); + + const exitCode = runFetchDiscussionTranscriptCli(["12"], { + env: { REPO_SLUG: "self-evolving/repo" }, + stdout: stdout.writer, + stderr: stderr.writer, + createClient() { + return { + graphql(): T { + throw new Error("not used by failing test"); + }, + } satisfies GraphQLClient; + }, + fetchDiscussionTranscript() { + throw new Error("Discussion #12 not found"); + }, + }); + + assert.equal(exitCode, 1); + assert.equal(stdout.read(), ""); + assert.match(stderr.read(), /Discussion #12 not found/); +}); diff --git a/.agent/src/__tests__/git.test.ts b/.agent/src/__tests__/git.test.ts new file mode 100644 index 0000000..7d2f06e --- /dev/null +++ b/.agent/src/__tests__/git.test.ts @@ -0,0 +1,25 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { buildPushToRefArgs } from "../git.js"; + +test("buildPushToRefArgs pushes HEAD to the target ref", () => { + assert.deepEqual( + buildPushToRefArgs("https://example.com/repo.git", "feature"), + ["push", "https://example.com/repo.git", "HEAD:feature"], + ); +}); + +test("buildPushToRefArgs includes a force-with-lease for branch updates", () => { + assert.deepEqual( + buildPushToRefArgs("https://example.com/repo.git", "feature", { + forceWithLeaseOid: "abc123", + }), + [ + "push", + "--force-with-lease=refs/heads/feature:abc123", + "https://example.com/repo.git", + "HEAD:feature", + ], + ); +}); diff --git a/.agent/src/__tests__/github.test.ts b/.agent/src/__tests__/github.test.ts new file mode 100644 index 0000000..6d2c04d --- /dev/null +++ b/.agent/src/__tests__/github.test.ts @@ -0,0 +1,71 @@ +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { dispatchWorkflow } from "../github.js"; + +function writeExecutable(path: string, content: string): void { + writeFileSync(path, content, { encoding: "utf8", mode: 0o755 }); +} + +test("dispatchWorkflow retries without inputs unsupported by the live workflow schema", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-dispatch-workflow-")); + const originalPath = process.env.PATH; + + try { + const binDir = join(tempDir, "bin"); + const payloadDir = join(tempDir, "payloads"); + const countPath = join(tempDir, "count"); + const logPath = join(tempDir, "gh.log"); + mkdirSync(binDir, { recursive: true }); + mkdirSync(payloadDir, { recursive: true }); + + writeExecutable(join(binDir, "gh"), [ + "#!/usr/bin/env bash", + "set -euo pipefail", + `count_path=${JSON.stringify(countPath)}`, + `payload_dir=${JSON.stringify(payloadDir)}`, + `log_path=${JSON.stringify(logPath)}`, + "count=0", + "if [[ -f \"$count_path\" ]]; then count=$(cat \"$count_path\"); fi", + "count=$((count + 1))", + "printf '%s' \"$count\" > \"$count_path\"", + "printf '%s\\n' \"$*\" >> \"$log_path\"", + "cat > \"$payload_dir/payload-$count.json\"", + "if [[ \"$count\" == \"1\" ]]; then", + " printf '%s\\n' '{\"message\":\"Unexpected inputs provided: [\\\"target_kind\\\", \\\"access_policy\\\"]\"}'", + " printf '%s\\n' 'gh: Unexpected inputs provided: [\"target_kind\", \"access_policy\"]' >&2", + " exit 1", + "fi", + "exit 0", + "", + ].join("\n")); + + process.env.PATH = `${binDir}:${originalPath || ""}`; + + dispatchWorkflow("self-evolving/repo", "agent-orchestrator.yml", "main", { + access_policy: "{}", + source_action: "fix-pr", + target_kind: "pull_request", + target_number: "20", + }); + + const firstPayload = JSON.parse(readFileSync(join(payloadDir, "payload-1.json"), "utf8")); + const retryPayload = JSON.parse(readFileSync(join(payloadDir, "payload-2.json"), "utf8")); + const log = readFileSync(logPath, "utf8").trim().split(/\r?\n/); + + assert.equal(log.length, 2); + assert.equal(firstPayload.inputs.target_kind, "pull_request"); + assert.equal(firstPayload.inputs.access_policy, "{}"); + assert.equal(retryPayload.ref, "main"); + assert.deepEqual(retryPayload.inputs, { + source_action: "fix-pr", + target_number: "20", + }); + } finally { + process.env.PATH = originalPath; + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/handoff.test.ts b/.agent/src/__tests__/handoff.test.ts new file mode 100644 index 0000000..486afba --- /dev/null +++ b/.agent/src/__tests__/handoff.test.ts @@ -0,0 +1,947 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + buildReviewFixPrHandoffContext, + buildHandoffDedupeKey, + buildHandoffMarker, + decideHandoff, + defaultFixPrHandoffContext, + extractReviewConclusion, + extractReviewRecommendedNextStep, + extractReviewActionItems, + formatHandoffMarkerComment, + getHandoffMarkerState, + hasHandoffMarker, + isPendingHandoffMarkerStale, + parseHandoffMarker, + parsePlannerDecision, + automationModeAllowsHandoff, + normalizeAutomationMode, +} from "../handoff.js"; + +test("handoff skips when automation mode is disabled", () => { + const decision = decideHandoff({ + automationMode: "disabled", + sourceAction: "implement", + sourceConclusion: "success", + targetNumber: "42", + nextTargetNumber: "99", + currentRound: 1, + maxRounds: 5, + }); + + assert.equal(decision.decision, "skip"); + assert.equal(decision.nextAction, undefined); +}); + +test("agent mode validates planner handoff against policy", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "implement", + sourceConclusion: "success", + targetNumber: "42", + nextTargetNumber: "99", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "review", + reason: "Implementation produced a PR.", + handoffContext: "Review the new PR with special attention to generated workflow permissions.", + }, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "review"); + assert.equal(decision.targetNumber, "99"); + assert.match(decision.reason, /agent planner selected review/); + assert.equal( + decision.handoffContext, + "Review the new PR with special attention to generated workflow permissions.", + ); +}); + +test("agent mode allows planner-selected self-approval for SHIP reviews when enabled", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "SHIP", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: true, + plannerDecision: { + decision: "handoff", + nextAction: "agent-self-approve", + reason: "Review shipped and self-approval is enabled.", + }, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "agent-self-approve"); + assert.equal(decision.targetNumber, "99"); + assert.match(decision.reason, /agent planner selected agent-self-approve/); +}); + +test("agent mode allows planner-selected self-merge after self-approval when enabled", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "agent-self-approve", + sourceConclusion: "approved", + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + allowSelfMerge: true, + plannerDecision: { + decision: "handoff", + nextAction: "agent-self-merge", + reason: "Self-approval completed and self-merge is enabled.", + }, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "agent-self-merge"); + assert.equal(decision.targetNumber, "99"); + assert.match(decision.reason, /agent planner selected agent-self-merge/); +}); + +test("agent mode supports issue-level child issue delegation", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "issue", + targetNumber: "76", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "delegate_issue", + reason: "Split the work into a child task.", + childStage: "stage 1", + childInstructions: "Implement the first stage.", + basePr: "66", + }, + }); + + assert.equal(decision.decision, "delegate_issue"); + assert.equal(decision.nextAction, undefined); + assert.equal(decision.targetNumber, "76"); + assert.equal(decision.childStage, "stage 1"); + assert.equal(decision.childInstructions, "Implement the first stage."); + assert.equal(decision.basePr, "66"); +}); + +test("agent mode supports issue-level orchestrate handoff to implement", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "issue", + targetNumber: "76", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "implement", + reason: "The current issue is small and self-contained.", + baseBranch: "feature-base", + }, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "implement"); + assert.equal(decision.targetNumber, "76"); + assert.equal(decision.nextRound, 2); + assert.match(decision.reason, /agent planner selected implement/); + assert.equal(decision.baseBranch, "feature-base"); +}); + +test("agent mode supports PR-level orchestrate handoff to review or fix-pr", () => { + const review = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "review", + reason: "The request asks for review before any edits.", + }, + }); + assert.equal(review.decision, "dispatch"); + assert.equal(review.nextAction, "review"); + assert.equal(review.targetNumber, "66"); + assert.match(review.reason, /agent planner selected review/); + + const fix = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "fix-pr", + reason: "The request explicitly asks to fix the PR.", + handoffContext: "Fix the merge conflict only.", + }, + }); + assert.equal(fix.decision, "dispatch"); + assert.equal(fix.nextAction, "fix-pr"); + assert.equal(fix.targetNumber, "66"); + assert.equal(fix.handoffContext, "Fix the merge conflict only."); + assert.match(fix.reason, /agent planner selected fix-pr/); +}); + +test("agent mode rejects invalid PR-level orchestrate handoffs", () => { + const implement = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "implement", + reason: "Try to implement from a PR.", + }, + }); + assert.equal(implement.decision, "stop"); + assert.match(implement.reason, /only for issue targets/); + + const mixedAnswer = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "answer", + nextAction: "review", + reason: "Answer and review.", + }, + }); + assert.equal(mixedAnswer.decision, "stop"); + assert.match(mixedAnswer.reason, /answer must not set next_action/); + + const fixWithoutContext = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "fix-pr", + reason: "Fix the PR.", + }, + }); + assert.equal(fixWithoutContext.decision, "stop"); + assert.match(fixWithoutContext.reason, /without handoff_context/); +}); + +test("agent mode rejects invalid child issue delegation", () => { + const wrongTarget = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "66", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "delegate_issue", + reason: "Try from a PR.", + childInstructions: "Do it.", + }, + }); + assert.equal(wrongTarget.decision, "stop"); + assert.match(wrongTarget.reason, /only from issues/); + + const missingInstructions = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "issue", + targetNumber: "76", + currentRound: 1, + maxRounds: 5, + plannerDecision: { decision: "delegate_issue", reason: "No task." }, + }); + assert.equal(missingInstructions.decision, "stop"); + assert.match(missingInstructions.reason, /without child instructions/); + + const mixedCommand = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "issue", + targetNumber: "76", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "delegate_issue", + nextAction: "review", + reason: "Mixed command.", + childInstructions: "Do it.", + }, + }); + assert.equal(mixedCommand.decision, "stop"); + assert.match(mixedCommand.reason, /must not set next_action/); +}); + +test("agent mode rejects issue-level implement handoffs for non-issue targets", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "requested", + targetKind: "pull_request", + targetNumber: "76", + currentRound: 1, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "implement", + reason: "Try to implement from a PR.", + }, + }); + + assert.equal(decision.decision, "stop"); + assert.match(decision.reason, /only for issue targets/); +}); + +test("agent mode falls back to default fix-pr context when planner omits it", () => { + const decision = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "minor_issues", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + plannerDecision: { + decision: "handoff", + nextAction: "fix-pr", + reason: "Review found minor issues.", + }, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "fix-pr"); + assert.equal(decision.handoffContext, defaultFixPrHandoffContext()); +}); + +test("agent mode stops invalid or disallowed planner handoffs", () => { + const disallowed = decideHandoff({ + automationMode: "agent", + sourceAction: "implement", + sourceConclusion: "verify_failed", + targetNumber: "42", + nextTargetNumber: "99", + currentRound: 1, + maxRounds: 5, + plannerDecision: { decision: "handoff", nextAction: "review", reason: "Try anyway." }, + }); + assert.equal(disallowed.decision, "stop"); + assert.match(disallowed.reason, /policy disallows/); + + const wrongEdge = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "minor_issues", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + plannerDecision: { decision: "handoff", nextAction: "review", reason: "Review again." }, + }); + assert.equal(wrongEdge.decision, "stop"); + assert.match(wrongEdge.reason, /policy only allows fix-pr/); +}); + +test("agent mode respects planner stop, invalid planner output, and round budget", () => { + const stopped = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "minor_issues", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + plannerDecision: { decision: "stop", reason: "Leave the remaining work to a maintainer." }, + }); + assert.equal(stopped.decision, "stop"); + assert.match(stopped.reason, /agent planner stop/); + + const blocked = decideHandoff({ + automationMode: "agent", + sourceAction: "orchestrate", + sourceConclusion: "done", + targetKind: "issue", + targetNumber: "76", + currentRound: 2, + maxRounds: 5, + plannerDecision: { + decision: "blocked", + reason: "Need the next child scope.", + userMessage: "I need a maintainer decision before continuing.", + clarificationRequest: "Should the next child stack on #112?", + }, + }); + assert.equal(blocked.decision, "stop"); + assert.equal(blocked.plannerDecisionKind, "blocked"); + assert.equal(blocked.userMessage, "I need a maintainer decision before continuing."); + assert.equal(blocked.clarificationRequest, "Should the next child stack on #112?"); + assert.match(blocked.reason, /agent planner blocked/); + + const invalid = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "minor_issues", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + }); + assert.equal(invalid.decision, "stop"); + assert.match(invalid.reason, /planner decision missing/); + + const exhausted = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "minor_issues", + targetNumber: "99", + currentRound: 5, + maxRounds: 5, + plannerDecision: { decision: "handoff", nextAction: "fix-pr", reason: "Try another fix pass." }, + }); + assert.equal(exhausted.decision, "stop"); + assert.match(exhausted.reason, /budget/); +}); + +test("implement success dispatches review for the created PR", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "implement", + sourceConclusion: "success", + targetNumber: "42", + nextTargetNumber: "99", + currentRound: 1, + maxRounds: 5, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "review"); + assert.equal(decision.targetNumber, "99"); + assert.equal(decision.nextRound, 2); +}); + +test("implement stops on failures and missing PR targets", () => { + const failed = decideHandoff({ + automationMode: "heuristics", + sourceAction: "implement", + sourceConclusion: "verify_failed", + targetNumber: "42", + nextTargetNumber: "99", + currentRound: 1, + maxRounds: 5, + }); + assert.equal(failed.decision, "stop"); + assert.match(failed.reason, /verify_failed/); + + const missingPr = decideHandoff({ + automationMode: "heuristics", + sourceAction: "implement", + sourceConclusion: "success", + targetNumber: "42", + currentRound: 1, + maxRounds: 5, + }); + assert.equal(missingPr.decision, "stop"); + assert.match(missingPr.reason, /pull request target/); +}); + +test("review verdicts dispatch fix-pr or stop", () => { + for (const verdict of ["NEEDS_REWORK", "CHANGES_REQUESTED", "minor-issues"]) { + const needsFix = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: verdict, + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + }); + + assert.equal(needsFix.decision, "dispatch"); + assert.equal(needsFix.nextAction, "fix-pr"); + assert.equal(needsFix.targetNumber, "99"); + assert.equal(needsFix.handoffContext, defaultFixPrHandoffContext()); + } + + const ship = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: "SHIP", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + }); + + assert.equal(ship.decision, "stop"); + assert.match(ship.reason, /SHIP/); + + const selfApprove = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: "SHIP", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: true, + }); + + assert.equal(selfApprove.decision, "dispatch"); + assert.equal(selfApprove.nextAction, "agent-self-approve"); + assert.equal(selfApprove.targetNumber, "99"); + assert.match(selfApprove.reason, /dispatching agent-self-approve/); +}); + +test("review HUMAN_DECISION dispatches self-approval when enabled", () => { + for (const verdict of ["SHIP", "MINOR_ISSUES", "NEEDS_REWORK"]) { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: verdict, + sourceRecommendedNextStep: "HUMAN_DECISION", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: true, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "agent-self-approve"); + assert.match(decision.reason, /HUMAN_DECISION/); + } +}); + +test("review HUMAN_DECISION stops when self-approval is disabled", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: "MINOR_ISSUES", + sourceRecommendedNextStep: "HUMAN_DECISION", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: false, + }); + + assert.equal(decision.decision, "stop"); + assert.match(decision.reason, /HUMAN_DECISION/); +}); + +test("agent mode validates review HUMAN_DECISION self-approval handoff", () => { + const allowed = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "MINOR_ISSUES", + sourceRecommendedNextStep: "HUMAN_DECISION", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: true, + plannerDecision: { + decision: "handoff", + nextAction: "agent-self-approve", + reason: "Review asked for human decision and self-approval is enabled.", + }, + }); + assert.equal(allowed.decision, "dispatch"); + assert.equal(allowed.nextAction, "agent-self-approve"); + + const wrong = decideHandoff({ + automationMode: "agent", + sourceAction: "review", + sourceConclusion: "MINOR_ISSUES", + sourceRecommendedNextStep: "HUMAN_DECISION", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + allowSelfApprove: true, + plannerDecision: { decision: "handoff", nextAction: "fix-pr", reason: "Fix it instead." }, + }); + assert.equal(wrong.decision, "stop"); + assert.match(wrong.reason, /policy only allows agent-self-approve/); +}); + +test("review fix-pr handoffs preserve derived source context", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "review", + sourceConclusion: "minor_issues", + sourceHandoffContext: "Fix only the failing fallback test.", + targetNumber: "99", + currentRound: 2, + maxRounds: 5, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "fix-pr"); + assert.equal(decision.handoffContext, "Fix only the failing fallback test."); +}); + +test("self-approval request changes dispatches fix-pr with handoff context", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "agent-self-approve", + sourceConclusion: "REQUEST_CHANGES", + sourceHandoffContext: "Tighten the resolver preflight and add tests.", + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "fix-pr"); + assert.equal(decision.targetNumber, "99"); + assert.equal(decision.handoffContext, "Tighten the resolver preflight and add tests."); +}); + +test("self-approval terminal conclusions stop", () => { + for (const conclusion of ["approved", "blocked", "failed"]) { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "agent-self-approve", + sourceConclusion: conclusion, + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + }); + + assert.equal(decision.decision, "stop"); + assert.equal(decision.nextAction, undefined); + assert.match(decision.reason, new RegExp(`agent-self-approve concluded ${conclusion}`)); + } +}); + +test("self-approval approved dispatches self-merge only when enabled", () => { + const disabled = decideHandoff({ + automationMode: "heuristics", + sourceAction: "agent-self-approve", + sourceConclusion: "approved", + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + }); + assert.equal(disabled.decision, "stop"); + + const enabled = decideHandoff({ + automationMode: "heuristics", + sourceAction: "agent-self-approve", + sourceConclusion: "approved", + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + allowSelfMerge: true, + }); + assert.equal(enabled.decision, "dispatch"); + assert.equal(enabled.nextAction, "agent-self-merge"); + assert.equal(enabled.targetNumber, "99"); + assert.match(enabled.reason, /dispatching agent-self-merge/); +}); + +test("self-merge terminal conclusions stop", () => { + for (const conclusion of ["merged", "auto_merge_enabled", "blocked", "failed"]) { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "agent-self-merge", + sourceConclusion: conclusion, + targetNumber: "99", + currentRound: 4, + maxRounds: 5, + }); + + assert.equal(decision.decision, "stop"); + assert.equal(decision.nextAction, undefined); + assert.match(decision.reason, new RegExp(`agent-self-merge concluded ${conclusion}`)); + } +}); + +test("fix-pr success dispatches review until the round budget is exhausted", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "fix-pr", + sourceConclusion: "success", + targetNumber: "99", + currentRound: 4, + maxRounds: 5, + }); + + assert.equal(decision.decision, "dispatch"); + assert.equal(decision.nextAction, "review"); + + const exhausted = decideHandoff({ + automationMode: "heuristics", + sourceAction: "fix-pr", + sourceConclusion: "success", + targetNumber: "99", + currentRound: 5, + maxRounds: 5, + }); + + assert.equal(exhausted.decision, "stop"); + assert.match(exhausted.reason, /budget/); +}); + +test("fix-pr unsatisfactory conclusions stop without re-review", () => { + for (const conclusion of ["no_changes", "failed", "verify_failed"]) { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "fix-pr", + sourceConclusion: conclusion, + targetNumber: "99", + currentRound: 3, + maxRounds: 5, + }); + + assert.equal(decision.decision, "stop"); + assert.equal(decision.nextAction, undefined); + assert.match(decision.reason, new RegExp(`fix-pr concluded ${conclusion}`)); + assert.match(decision.reason, /must succeed before re-review/); + } +}); + +test("unsupported actions stop", () => { + const decision = decideHandoff({ + automationMode: "heuristics", + sourceAction: "deploy", + sourceConclusion: "success", + targetNumber: "99", + currentRound: 1, + maxRounds: 5, + }); + + assert.equal(decision.decision, "stop"); + assert.match(decision.reason, /unsupported/); +}); + +test("extractReviewConclusion reads final verdict markdown", () => { + assert.equal(extractReviewConclusion("## Final Verdict\n- `MINOR_ISSUES`"), "minor_issues"); + assert.equal(extractReviewConclusion("Final answer\n\n## Final Verdict\nSHIP"), "ship"); + assert.equal(extractReviewConclusion("This needs-rework before another pass"), "needs_rework"); + assert.equal(extractReviewConclusion("No verdict here"), "unknown"); +}); + +test("extractReviewRecommendedNextStep reads review synthesis recommendation", () => { + assert.equal( + extractReviewRecommendedNextStep("## Recommended Next Step\nHUMAN_DECISION: Needs gate judgment."), + "human_decision", + ); + assert.equal( + extractReviewRecommendedNextStep("## Recommended Next Step\n- `FIX_PR`"), + "fix_pr", + ); + assert.equal(extractReviewRecommendedNextStep("No recommendation"), ""); +}); + +test("handoff dedupe markers are deterministic and detectable", () => { + const key = buildHandoffDedupeKey({ + repo: "Self-Evolving/Repo", + sourceRunId: "12345", + sourceAction: "fix-pr", + sourceTargetNumber: "99", + nextAction: "review", + nextTargetNumber: "99", + nextRound: 3, + }); + + assert.equal(key, "handoff:self-evolving/repo:12345:fix_pr:99:review:99:3"); + const marker = buildHandoffMarker(key, "pending", 1_000); + assert.ok(hasHandoffMarker(`comment body\n${marker}`, key)); + assert.equal(getHandoffMarkerState(`comment body\n${marker}`, key), "pending"); + assert.deepEqual(parseHandoffMarker(marker, key), { state: "pending", createdAtMs: 1_000 }); + assert.equal(getHandoffMarkerState(buildHandoffMarker(key, "failed"), key), "failed"); + assert.equal(getHandoffMarkerState(buildHandoffMarker(key), key), "dispatched"); + assert.equal(hasHandoffMarker("comment body", key), false); +}); + +test("handoff marker comments use compact tables and fix-pr task context", () => { + const key = buildHandoffDedupeKey({ + repo: "self-evolving/repo", + sourceRunId: "12345", + sourceAction: "review", + sourceTargetNumber: "128", + nextAction: "fix-pr", + nextTargetNumber: "128", + nextRound: 6, + }); + + const body = formatHandoffMarkerComment({ + key, + state: "dispatched", + sourceAction: "review", + nextAction: "fix-pr", + targetKind: "pull_request", + targetNumber: "128", + nextRound: 6, + maxRounds: 10, + reason: "review verdict is minor_issues; dispatching fix-pr", + handoffContext: "Document and test the metadata path fallback.", + createdAtMs: 1_000, + }); + + assert.match(body, /Sepo is dispatching follow-up automation\./); + assert.match(body, /\| Source \| Next \| Target \| Round \| Status \|/); + assert.match(body, /\| review \| fix-pr \| PR #128 \| 6 \/ 10 \| Dispatched \|/); + assert.match(body, /Reason: review verdict is minor_issues; dispatching fix-pr/); + assert.match(body, /Task for fix-pr:\nDocument and test the metadata path fallback\./); + assert.match(body, //m); + const issueBody = readOnboardingIssueBody( + log, + /^issue create --title Sepo setup check --body-file ([^ ]*sepo-onboarding-[a-f0-9]+\.md) --repo self-evolving\/repo$/m, + ); + assert.equal(issueBody, expectedSetupIssueBody); + assert.doesNotMatch(issueBody, /@sepo-agent/); + assert.match(log, /## Sepo setup status/); + assert.match(log, /### Current status/); + assert.match(log, /GitHub App\/auth: resolved via `oidc_broker`/); + assert.match(log, /Model credentials: `OPENAI_API_KEY` configured/); + assert.match(log, /Agent provider: `codex` \(OPENAI_API_KEY is configured\)/); + assert.match(log, /Memory: initialized \(`agent\/memory`\)/); + assert.match(log, /Rubrics: not initialized/); + assert.match(log, /Optional: run \*\*Actions > Agent \/ Rubrics \/ Initialization\*\*\./); + assert.match(log, /### Remaining setup/); + assert.match(log, /Optional: initialize rubrics branch `agent\/rubrics`\./); + assert.match(log, /### Test Sepo/); + assert.match(log, /@sepo-agent \/answer Is Sepo configured correctly in this repository\?/); + assert.match(log, /@sepo-agent \/implement Create a small README update that verifies the agent can open a PR\./); + assert.match(log, /@sepo-agent \/review/); + assert.match(log, /Last checked: https:\/\/github.com\/self-evolving\/repo\/actions\/runs\/1/); + assert.doesNotMatch(log, /Built-in trigger labels:/); + assert.doesNotMatch(log, /`agent\/fix-pr` ->/); + assert.match(log, /agent\/fix-pr/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("onboarding-check CLI updates an existing marker comment", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-onboarding-")); + + try { + const logPath = join(tempDir, "gh.log"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "label" ] && [ "$2" = "list" ]; then + printf '%s\\n' "$4" + exit 0 +fi +if [ "$1" = "api" ] && [[ "$2" == repos/*/git/matching-refs/heads/* ]]; then + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "list" ]; then + printf '[{"number":5,"title":"Sepo setup check"}]' + exit 0 +fi +if [ "$1" = "api" ] && [[ "$2" == repos/*/issues/5/comments ]]; then + printf '[{"id":123,"body":" old"}]' + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "edit" ]; then + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "-X" ] && [ "$3" = "PATCH" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = runOnboarding(tempDir, { + AUTH_MODE: "", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + }); + + assert.equal(result.status, 0, result.stderr); + const log = readFileSync(logPath, "utf8"); + assert.doesNotMatch(log, /^issue create /m); + assert.doesNotMatch(log, /^label create /m); + assert.match(log, /^issue edit 5 --repo self-evolving\/repo --body-file .+$/m); + const updatedIssueBody = readOnboardingIssueBody( + log, + /^issue edit 5 --repo self-evolving\/repo --body-file ([^ ]*sepo-onboarding-[a-f0-9]+\.md)$/m, + ); + assert.equal(updatedIssueBody, expectedSetupIssueBody); + assert.doesNotMatch(updatedIssueBody, /@sepo-agent/); + assert.match(log, /^api -X PATCH repos\/self-evolving\/repo\/issues\/comments\/123 -f body=/m); + assert.match(log, /GitHub App\/auth: not resolved/); + assert.match(log, /Model credentials: not configured/); + assert.match(log, /Add `OPENAI_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret\./); + assert.match(log, /Memory: not initialized/); + assert.match(log, /Run \*\*Actions > Agent \/ Memory \/ Initialization\*\*\./); + assert.match(log, /Configure one model provider credential\./); + assert.doesNotMatch(log, /Built-in trigger labels:/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/orchestrate-handoff-cli.test.ts b/.agent/src/__tests__/orchestrate-handoff-cli.test.ts new file mode 100644 index 0000000..a7656ba --- /dev/null +++ b/.agent/src/__tests__/orchestrate-handoff-cli.test.ts @@ -0,0 +1,1852 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + return outputs; +} + +function runOrchestrateHandoff(env: Record): { + status: number | null; + stderr: string; + stdout: string; + outputs: Map; + ghLog: string; + dispatchPayload: Record | null; +} { + const tempDir = mkdtempSync(join(tmpdir(), "agent-orchestrate-handoff-")); + try { + const fakeGh = join(tempDir, "gh"); + const outputPath = join(tempDir, "github-output.txt"); + const ghLogPath = join(tempDir, "gh.log"); + const dispatchPayloadPath = join(tempDir, "dispatch.json"); + const plannerResponse = env.FAKE_PLANNER_RESPONSE || ""; + const plannerResponseFile = join(tempDir, "planner-response.md"); + const runEnv = { ...env }; + if (plannerResponse) { + writeFileSync(plannerResponseFile, plannerResponse, "utf8"); + runEnv.PLANNER_RESPONSE_FILE = plannerResponseFile; + delete runEnv.FAKE_PLANNER_RESPONSE; + } + + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + `#!/usr/bin/env bash +set -euo pipefail +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" + +if [ "\${1-}" = "pr" ] && [ "\${2-}" = "view" ]; then + if [ "\${FAKE_PR_STATUS_MODE-}" = "missing" ]; then + exit 1 + fi + if [[ "$*" == *"body"* ]]; then + printf '{"body":"%s"}\\n' "\${FAKE_PR_BODY-}" + exit 0 + fi + printf '{"state":"%s","reviewDecision":"%s"}\\n' "\${FAKE_PR_STATE-OPEN}" "\${FAKE_PR_REVIEW_DECISION-}" + exit 0 +fi + +if [ "\${1-}" = "issue" ] && [ "\${2-}" = "view" ]; then + if [ "\${FAKE_ISSUE_VIEW_MODE-}" = "missing" ]; then + exit 1 + fi + issue_url="\${FAKE_ISSUE_URL-}" + if [ -z "$issue_url" ]; then + issue_url="https://github.com/self-evolving/repo/issues/\${3}" + fi + printf '{"number":%s,"title":"%s","body":"%s","author":{"login":"%s"},"state":"%s","url":"%s"}\\n' "\${3}" "\${FAKE_ISSUE_TITLE-Child issue}" "\${FAKE_ISSUE_BODY-}" "\${FAKE_ISSUE_AUTHOR-sepo-agent-app[bot]}" "\${FAKE_ISSUE_STATE-OPEN}" "$issue_url" + exit 0 +fi + +if [ "\${1-}" = "issue" ] && [ "\${2-}" = "list" ]; then + printf '%s\\n' "\${FAKE_ISSUE_LIST_JSON-[]}" + exit 0 +fi + +if [ "\${1-}" = "issue" ] && [ "\${2-}" = "create" ]; then + printf 'https://github.com/self-evolving/repo/issues/%s\\n' "\${FAKE_CREATED_ISSUE_NUMBER-77}" + exit 0 +fi + +if [ "\${1-}" = "issue" ] && [ "\${2-}" = "edit" ]; then + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "--paginate" ] && [ "\${3-}" = "--slurp" ]; then + printf '%s\\n' "\${FAKE_ISSUE_COMMENTS_JSON-[]}" + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "--paginate" ] && [[ "\${3-}" == repos/*/issues/*/sub_issues ]]; then + if [ "\${FAKE_SUB_ISSUES_MODE-}" = "error" ]; then + printf 'sub-issues unavailable\\n' >&2 + exit 1 + fi + printf '%s\\n' "\${FAKE_SUB_ISSUE_NUMBERS-}" + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "graphql" ]; then + if [ "\${FAKE_GRAPHQL_MODE-}" = "error" ]; then + printf '{"errors":[{"message":"graphql unavailable"}]}\\n' + exit 0 + fi + case "$*" in + *ViewerLogin*) + printf '{"data":{"viewer":{"login":"sepo-agent-app[bot]"}}}\\n' + ;; + *IssueGeneratedComments*) + printf '{"data":{"repository":{"issue":{"comments":{"nodes":%s,"pageInfo":{"hasNextPage":false,"endCursor":null}}}}}}\\n' "\${FAKE_GRAPHQL_ISSUE_COMMENTS-[]}" + ;; + *PullRequestReviewSummaryComments*) + printf '{"data":{"repository":{"pullRequest":{"comments":{"nodes":%s,"pageInfo":{"hasNextPage":false,"endCursor":null}}}}}}\\n' "\${FAKE_GRAPHQL_PR_COMMENTS-[]}" + ;; + *MinimizeReviewSummary*) + printf '{"data":{"minimizeComment":{"minimizedComment":{"isMinimized":true}}}}\\n' + ;; + *) + printf 'unexpected graphql query: %s\\n' "$*" >&2 + exit 1 + ;; + esac + exit 0 +fi + +if [ "\${1-}" = "api" ] && [[ "\${2-}" == repos/*/issues/* ]] && [ "\${3-}" = "--jq" ] && [ "\${4-}" = ".id" ]; then + if [ "\${FAKE_ISSUE_REST_MODE-}" = "missing" ]; then + printf 'issue rest lookup failed\\n' >&2 + exit 1 + fi + printf '%s\\n' "\${FAKE_ISSUE_REST_ID-170077}" + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "--method" ] && [ "\${3-}" = "POST" ] && [[ "\${4-}" == repos/*/issues/*/sub_issues ]]; then + if [ "\${FAKE_SUB_ISSUE_LINK_MODE-}" = "error" ]; then + printf 'sub-issue link failed\\n' >&2 + exit 1 + fi + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "--method" ] && [ "\${3-}" = "POST" ] && [[ "\${4-}" == repos/*/issues/*/comments ]]; then + printf '%s\\n' "\${FAKE_MARKER_ID-9001}" + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "--method" ] && [ "\${3-}" = "PATCH" ] && [[ "\${4-}" == repos/*/issues/comments/* ]]; then + exit 0 +fi + +if [ "\${1-}" = "api" ] && [ "\${2-}" = "-X" ] && [ "\${3-}" = "POST" ] && [[ "\${4-}" == repos/*/actions/workflows/*/dispatches ]]; then + cat > "$FAKE_DISPATCH_PAYLOAD" + exit 0 +fi + +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + const childEnv: NodeJS.ProcessEnv = { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GITHUB_OUTPUT: outputPath, + GH_TOKEN: "fake-token", + GITHUB_REPOSITORY: "self-evolving/repo", + DEFAULT_BRANCH: "main", + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "requested", + SOURCE_RUN_ID: "12345", + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + REQUESTED_BY: "lolipopshock", + REQUEST_TEXT: "@sepo-agent /orchestrate", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "1", + AUTOMATION_MAX_ROUNDS: "5", + ACCESS_POLICY: "", + AUTHOR_ASSOCIATION: "MEMBER", + AGENT_ALLOW_SELF_MERGE: "false", + BASE_BRANCH: "", + BASE_PR: "", + REPOSITORY_PRIVATE: "true", + FAKE_GH_LOG: ghLogPath, + FAKE_DISPATCH_PAYLOAD: dispatchPayloadPath, + }; + for (const [key, value] of Object.entries(runEnv)) { + if (value === undefined) { + delete childEnv[key]; + } else { + childEnv[key] = value; + } + } + + const result = spawnSync("node", [".agent/dist/cli/orchestrate-handoff.js"], { + cwd: repoRoot, + env: childEnv, + encoding: "utf8", + }); + + let ghLog = ""; + if (existsSync(ghLogPath)) { + try { + ghLog = readFileSync(ghLogPath, "utf8"); + } catch { + ghLog = ""; + } + } + let dispatchPayload: Record | null = null; + if (existsSync(dispatchPayloadPath)) { + try { + dispatchPayload = JSON.parse(readFileSync(dispatchPayloadPath, "utf8")); + } catch { + dispatchPayload = null; + } + } + + return { + status: result.status, + stderr: result.stderr, + stdout: result.stdout, + outputs: parseGithubOutput(outputPath), + ghLog, + dispatchPayload, + }; + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +} + +test("manual orchestrate stops when round budget is exhausted", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_CURRENT_ROUND: "5", + AUTOMATION_MAX_ROUNDS: "5", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "automation round budget exhausted"); +}); + +test("manual orchestrate stops for unsupported target kind", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "discussion", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "unsupported target kind discussion"); +}); + +test("manual orchestrate stops when PR status cannot be read", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATUS_MODE: "missing", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "could not read pull request status"); +}); + +test("manual orchestrate stops for non-open PR targets", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "CLOSED", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "pull request is closed"); +}); + +test("manual orchestrate dispatches implement for issue targets", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + BASE_PR: "12", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "implement"); + assert.match(run.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); + assert.equal((run.dispatchPayload?.inputs as Record).base_pr, "12"); +}); + +test("manual orchestrate defaults automation max rounds to 12 when env is absent", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTOMATION_MAX_ROUNDS: undefined, + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "implement"); + assert.match(run.ghLog, /\| orchestrate \| implement \| Issue #20 \| 2 \/ 12 \| Dispatched \|/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.automation_max_rounds, "12"); +}); + +test("agent orchestrate dispatches implement directly for self-contained issue targets", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + BASE_BRANCH: "", + BASE_PR: "", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "implement", + reason: "The requested change is scoped to the current issue.", + base_branch: "planner-base", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "implement"); + assert.equal(run.outputs.get("target_number"), "76"); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.issue_number, "76"); + assert.equal(inputs.automation_mode, "agent"); + assert.equal(inputs.automation_current_round, "2"); + assert.equal(inputs.orchestration_enabled, "true"); + assert.equal(inputs.base_branch, "planner-base"); +}); + +test("agent orchestrate rejects effective implement base input conflicts", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + BASE_PR: "12", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "implement", + reason: "The requested change is scoped to the current issue.", + base_branch: "planner-base", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.equal(run.outputs.get("target_number"), "76"); + assert.equal(run.outputs.get("reason"), "set only one of base_branch or base_pr for implementation"); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); + assert.equal(run.dispatchPayload, null); +}); + +test("agent orchestrate delegates to a child issue without extending AgentAction", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + BASE_BRANCH: "", + BASE_PR: "", + FAKE_CREATED_ISSUE_NUMBER: "77", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Split into a child task.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + base_pr: "66", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("next_action"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "77"); + assert.match(run.ghLog, /issue create/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /Sepo is starting a focused child task for this orchestration\./); + assert.match(run.ghLog, /\| Child task \| Focus \| Parent issue \| Status \|/); + assert.match(run.ghLog, /\| #77 \| stage-1 \| #76 \| Running \|/); + assert.match(run.ghLog, //); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/sub_issues/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/77 --jq \.id/); + assert.match(run.ghLog, /-F sub_issue_id=170077/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_action, "orchestrate"); + assert.equal(inputs.source_conclusion, "delegated"); + assert.equal(inputs.target_kind, "issue"); + assert.equal(inputs.target_number, "77"); + assert.equal(inputs.automation_mode, "heuristics"); + assert.equal(inputs.base_pr, "66"); +}); + +test("agent orchestrate skips GitHub sub-issue POST when relation already exists", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_CREATED_ISSUE_NUMBER: "77", + FAKE_SUB_ISSUE_NUMBERS: "77", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Split into a child task.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/sub_issues/); + assert.doesNotMatch(run.ghLog, /repos\/self-evolving\/repo\/issues\/77 --jq \.id/); + assert.doesNotMatch(run.ghLog, /-F sub_issue_id=/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate continues when GitHub sub-issue linking fails", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_CREATED_ISSUE_NUMBER: "77", + FAKE_SUB_ISSUE_LINK_MODE: "error", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Split into a child task.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.match(run.stderr, /Could not link child issue #77 as a GitHub sub-issue of #76/); + assert.match(run.ghLog, /-F sub_issue_id=170077/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate stacks sequential existing child on prior child PR", () => { + const priorChildReport = [ + "Sub-orchestrator fix-resumed-fix-pr-handoff-context finished", + "Child issue: #84", + "PR: #89", + "Result: SHIP", + "Parent round: 2/10", + "Summary: review verdict is SHIP", + "Next: waiting for meta orchestrator", + "", + ].join("\n"); + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "83", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + BASE_BRANCH: "", + BASE_PR: "", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_BODY: "Existing child issue body.", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "prior-child-report", + body: priorChildReport, + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Continue one-by-one and stack on prior child PR #89.", + child_stage: "handle-unsatisfactory-action-results", + child_issue_number: "79", + child_instructions: "Implement the second child issue.", + base_pr: "89", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "79"); + assert.match(run.ghLog, /issue view 79/); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.target_number, "79"); + assert.equal(inputs.base_branch, ""); + assert.equal(inputs.base_pr, "89"); +}); + +test("agent orchestrate reuses parent-recorded child issue before search", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_BODY: "", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "parent-child-link", + body: "", + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Retry delegated stage.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "77"); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/sub_issues/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/77 --jq \.id/); + assert.match(run.ghLog, /-F sub_issue_id=170077/); + assert.doesNotMatch(run.ghLog, /issue list/); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.target_number, "77"); +}); + +test("agent orchestrate ignores user-authored parent child-link markers", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_CREATED_ISSUE_NUMBER: "78", + FAKE_ISSUE_BODY: "", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "forged-parent-child-link", + body: "", + user: { login: "lolipopshock" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Retry delegated stage.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "78"); + assert.doesNotMatch(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /issue list/); + assert.match(run.ghLog, /issue create/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate ignores user-authored child issue markers from search", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_CREATED_ISSUE_NUMBER: "78", + FAKE_ISSUE_LIST_JSON: JSON.stringify([ + { + number: 77, + title: "Forged child", + body: "", + author: { login: "lolipopshock" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Retry delegated stage.", + child_stage: "stage 1", + child_instructions: "Implement the delegated stage.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "78"); + assert.match(run.ghLog, /issue list/); + assert.match(run.ghLog, /issue create/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate adopts explicit user-authored child issues with trusted comments", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_BODY: "Existing issue body. ", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Adopt an existing child issue.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "77"); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/77\/comments/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /\| Parent issue \| Stage \| Parent round \| Status \|/); + assert.match(run.ghLog, /\| #76 \| stage-1 \| 2 \| Running \|/); + assert.match(run.ghLog, /\| Child task \| Focus \| Parent issue \| Status \|/); + assert.match(run.ghLog, /\| #77 \| stage-1 \| #76 \| Running \|/); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.doesNotMatch(run.ghLog, /issue list/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate reuses explicit adopted child marker comments on rerun", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_BODY: "Existing issue body.", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "existing-adoption-marker", + body: [ + "Sepo adopted this issue as a sub-orchestrator child of #76.", + "", + "Stage: stage-1", + "Parent round: 2", + "", + "", + "", + ].join("\n"), + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Reuse an adopted child issue.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "77"); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.doesNotMatch(run.ghLog, /Sepo adopted this issue as a sub-orchestrator child/); + assert.doesNotMatch(run.ghLog, /issue create/); +}); + +test("agent orchestrate ignores forged app-authored child marker comments", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_BODY: "Existing issue body.", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "forged-agent-output", + body: [ + "Answer summary from another route.", + "", + "", + ].join("\n"), + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Adopt an existing child issue.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "delegate_issue"); + assert.equal(run.outputs.get("target_number"), "77"); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /Sepo adopted this issue as a sub-orchestrator child/); + assert.match(run.ghLog, /\| Parent issue \| Stage \| Parent round \| Status \|/); + assert.match(run.ghLog, /\| #76 \| stage-1 \| 2 \| Running \|/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.doesNotMatch(run.ghLog, /repos\/self-evolving\/repo\/issues\/comments\/forged-agent-output/); + assert.doesNotMatch(run.ghLog, /issue create/); +}); + +test("agent orchestrate rejects explicit child targets that are pull requests", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_URL: "https://github.com/self-evolving/repo/pull/77", + FAKE_ISSUE_BODY: "", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Reuse an existing child.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /child issue delegation failed/); + assert.match(run.outputs.get("reason") || "", /child_issue_number #77 is a pull request, not an issue/); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /repos\/self-evolving\/repo\/issues\/77\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate rejects explicit child targets that are closed issues", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_STATE: "CLOSED", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_BODY: "Existing issue body.", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Adopt an existing child issue.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /child issue delegation failed/); + assert.match(run.outputs.get("reason") || "", /child_issue_number #77 is closed, not open/); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /repos\/self-evolving\/repo\/issues\/77\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate reports invalid child issue reuse on the parent issue", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_ISSUE_BODY: "", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Reuse an existing child.", + child_stage: "stage 1", + child_issue_number: "77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /child issue delegation failed/); + assert.match(run.outputs.get("reason") || "", /belongs to parent #99, not #76/); + assert.match(run.ghLog, /issue view 77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate rejects malformed child issue numbers visibly", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Reuse a malformed child.", + child_stage: "stage 1", + child_issue_number: "issue-77", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /child issue delegation failed/); + assert.match(run.outputs.get("reason") || "", /child_issue_number must be a positive issue number: issue-77/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.doesNotMatch(run.ghLog, /issue list/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("agent orchestrate reports resumed child setup failures on the parent issue", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "delegate_issue", + reason: "Reuse a malformed child in a later round.", + child_stage: "stage 2", + child_issue_number: "issue-78", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /child issue delegation failed/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /issue create/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("manual orchestrate collapses old handoff comments after dispatch", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + FAKE_MARKER_ID: "current-handoff", + FAKE_GRAPHQL_ISSUE_COMMENTS: JSON.stringify([ + { + id: "old-handoff", + body: "", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + { + id: "current-handoff", + body: "", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + ]), + }); + + assert.equal(run.status, 0); + assert.match(run.stdout, /Collapsed 1 previous orchestrator handoff comment/); + assert.match(run.ghLog, /id=old-handoff/); + assert.doesNotMatch(run.ghLog, /id=current-handoff/); +}); + +test("manual orchestrate skips handoff cleanup when disabled", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AGENT_COLLAPSE_OLD_REVIEWS: "false", + }); + + assert.equal(run.status, 0); + assert.doesNotMatch(run.ghLog, /graphql/); +}); + +test("manual orchestrate keeps dispatch when handoff cleanup fails", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + FAKE_GRAPHQL_MODE: "error", + }); + + assert.equal(run.status, 0); + assert.match(run.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); + assert.match(run.stderr, /Failed to collapse previous orchestrator handoff comments/); +}); + +test("manual orchestrate dispatches fix-pr for PR targets with CHANGES_REQUESTED", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "CHANGES_REQUESTED", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "fix-pr"); + assert.match( + run.outputs.get("handoff_context") || "", + /latest unresolved requested-change review comments/, + ); + assert.doesNotMatch(run.outputs.get("handoff_context") || "", /review synthesis action items/); + assert.match(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + assert.match(run.ghLog, /Task for fix-pr:/); + assert.match(run.ghLog, /latest unresolved requested-change review comments/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.orchestrator_context, run.outputs.get("handoff_context")); +}); + +test("agent orchestrate dispatches planner-selected fix-pr for PR targets", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "APPROVED", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "fix-pr", + reason: "The request explicitly asks to fix this PR.", + handoff_context: "Fix only the merge conflict requested by the user.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "fix-pr"); + assert.equal(run.outputs.get("target_number"), "21"); + assert.match(run.outputs.get("reason") || "", /agent planner selected fix-pr/); + assert.equal(run.outputs.get("handoff_context"), "Fix only the merge conflict requested by the user."); + assert.match(run.ghLog, /pr view 21/); + assert.match(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.pr_number, "21"); + assert.equal(inputs.automation_mode, "agent"); + assert.equal(inputs.orchestrator_context, run.outputs.get("handoff_context")); +}); + +test("agent orchestrate stops planner-selected PR fix-pr without context", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "APPROVED", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "fix-pr", + reason: "The request asks to fix CI on this approved PR.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.equal(run.outputs.get("handoff_context"), ""); + assert.equal(run.outputs.get("reason"), "agent planner selected fix-pr for PR orchestration without handoff_context"); + assert.match(run.ghLog, /pr view 21/); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.doesNotMatch(run.ghLog, /latest unresolved requested-change review comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + assert.equal(run.dispatchPayload, null); +}); + +test("agent orchestrate dispatches planner-selected review for PR targets", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "APPROVED", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "review", + reason: "The request asks for review before branch changes.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "review"); + assert.match(run.outputs.get("reason") || "", /agent planner selected review/); + assert.match(run.ghLog, /actions\/workflows\/agent-review\.yml\/dispatches/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); +}); + +test("agent orchestrate stops before planner handoff for closed PR targets", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "CLOSED", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "handoff", + next_action: "fix-pr", + reason: "Try anyway.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.equal(run.outputs.get("reason"), "pull request is closed"); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); +}); + +test("agent orchestrate posts planner answers for PR targets without dispatch", () => { + const run = runOrchestrateHandoff({ + AUTOMATION_MODE: "agent", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "APPROVED", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "answer", + reason: "The user asked which route is appropriate.", + user_message: "Use `/review` for analysis-only PR feedback and `/fix-pr` when you want branch edits.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.match(run.outputs.get("reason") || "", /agent planner answered/); + assert.match(run.ghLog, /Sepo answered this orchestration request/); + assert.match(run.ghLog, /Use `\/review` for analysis-only PR feedback/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("review handoff dispatches fix-pr with visible task context", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "minor_issues", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "5", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_HANDOFF_CONTEXT: [ + "Address only the latest review synthesis action items:", + "- Document and test the metadata path fallback.", + "", + "Constraints: Ignore optional INFO notes.", + ].join("\n"), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "fix-pr"); + assert.equal( + run.outputs.get("handoff_context"), + [ + "Address only the latest review synthesis action items:", + "- Document and test the metadata path fallback.", + "", + "Constraints: Ignore optional INFO notes.", + ].join("\n"), + ); + assert.match(run.ghLog, /Sepo is dispatching follow-up automation\./); + assert.match(run.ghLog, /\| Source \| Next \| Target \| Round \| Status \|/); + assert.match(run.ghLog, /\| review \| fix-pr \| PR #128 \| 6 \/ 10 \| Dispatched \|/); + assert.match(run.ghLog, /Task for fix-pr:/); + assert.match(run.ghLog, /Document and test the metadata path fallback/); + assert.match(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.orchestrator_context, run.outputs.get("handoff_context")); +}); + +test("review SHIP dispatches self-approval when enabled", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "5", + AGENT_ALLOW_SELF_APPROVE: "true", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "agent-self-approve"); + assert.equal(run.outputs.get("target_number"), "128"); + assert.match(run.outputs.get("reason") || "", /review verdict is SHIP/); + assert.match(run.ghLog, /actions\/workflows\/agent-self-approve\.yml\/dispatches/); + assert.match(run.ghLog, /\| review \| agent-self-approve \| PR #128 \| 3 \/ 5 \| Dispatched \|/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.pr_number, "128"); + assert.equal(inputs.orchestration_enabled, "true"); + assert.equal(inputs.automation_current_round, "3"); +}); + +test("review HUMAN_DECISION dispatches self-approval with source fields", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "MINOR_ISSUES", + SOURCE_RECOMMENDED_NEXT_STEP: "HUMAN_DECISION", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "5", + AGENT_ALLOW_SELF_APPROVE: "true", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "agent-self-approve"); + assert.match(run.outputs.get("reason") || "", /HUMAN_DECISION/); + assert.match(run.ghLog, /actions\/workflows\/agent-self-approve\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.pr_number, "128"); + assert.equal(inputs.source_conclusion, "MINOR_ISSUES"); + assert.equal(inputs.source_recommended_next_step, "HUMAN_DECISION"); +}); + +test("review SHIP stops when self-approval is disabled", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "5", + AGENT_ALLOW_SELF_APPROVE: "false", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "review verdict is SHIP"); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-self-approve\.yml\/dispatches/); + assert.equal(run.dispatchPayload, null); +}); + +test("self-approval request changes dispatches fix-pr with context", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "agent-self-approve", + SOURCE_CONCLUSION: "request_changes", + SOURCE_HANDOFF_CONTEXT: "Update the resolver guard and add regression coverage.", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "3", + AUTOMATION_MAX_ROUNDS: "5", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "fix-pr"); + assert.equal(run.outputs.get("handoff_context"), "Update the resolver guard and add regression coverage."); + assert.match(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + assert.match(run.ghLog, /Task for fix-pr:/); + assert.match(run.ghLog, /Update the resolver guard and add regression coverage\./); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.pr_number, "128"); + assert.equal(inputs.orchestrator_context, "Update the resolver guard and add regression coverage."); + assert.equal(inputs.automation_current_round, "4"); +}); + +test("self-approval request changes respects the round budget", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "agent-self-approve", + SOURCE_CONCLUSION: "request_changes", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "5", + AUTOMATION_MAX_ROUNDS: "5", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "automation round budget exhausted"); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-fix-pr\.yml\/dispatches/); + assert.equal(run.dispatchPayload, null); +}); + +test("self-approval approved dispatches self-merge when enabled", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "agent-self-approve", + SOURCE_CONCLUSION: "approved", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "3", + AUTOMATION_MAX_ROUNDS: "5", + AGENT_ALLOW_SELF_MERGE: "true", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "agent-self-merge"); + assert.equal(run.outputs.get("target_number"), "128"); + assert.match(run.outputs.get("reason") || "", /dispatching agent-self-merge/); + assert.match(run.ghLog, /actions\/workflows\/agent-self-merge\.yml\/dispatches/); + assert.match(run.ghLog, /\| agent-self-approve \| agent-self-merge \| PR #128 \| 4 \/ 5 \| Dispatched \|/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.pr_number, "128"); + assert.equal(inputs.orchestration_enabled, "true"); + assert.equal(inputs.automation_current_round, "4"); +}); + +test("self-approval approved keeps current stop behavior when self-merge is disabled", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "agent-self-approve", + SOURCE_CONCLUSION: "approved", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "128", + AUTOMATION_CURRENT_ROUND: "3", + AUTOMATION_MAX_ROUNDS: "5", + AGENT_ALLOW_SELF_MERGE: "false", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "agent-self-approve concluded approved"); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-self-merge\.yml\/dispatches/); + assert.equal(run.dispatchPayload, null); +}); + +test("terminal self-approval child reports approval to parent", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "agent-self-approve", + SOURCE_CONCLUSION: "approved", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "3", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: childBody, + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "agent-self-approve concluded approved"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /\| #77 \| #88 \| Ready to ship \| 2 \/ 5 \| Resuming parent orchestration \|/); + assert.match(run.ghLog, /Summary: agent-self-approve concluded approved/); + assert.match(run.ghLog, //); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_action, "orchestrate"); + assert.equal(inputs.source_conclusion, "done"); + assert.equal(inputs.target_number, "76"); + assert.equal(inputs.automation_mode, "agent"); +}); + +test("manual orchestrate dispatches review for open PR targets without CHANGES_REQUESTED", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "pull_request", + TARGET_NUMBER: "21", + FAKE_PR_STATE: "OPEN", + FAKE_PR_REVIEW_DECISION: "APPROVED", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "dispatch"); + assert.equal(run.outputs.get("next_action"), "review"); + assert.match(run.ghLog, /actions\/workflows\/agent-review\.yml\/dispatches/); +}); + +test("initial orchestrate checks delegated route capabilities before dispatch", () => { + const run = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: JSON.stringify({ + route_overrides: { + implement: ["MEMBER"], + }, + }), + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal( + run.outputs.get("reason"), + "orchestrate requests require implement access; implement currently requires MEMBER access.", + ); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/20\/comments/); + assert.match(run.ghLog, /Source conclusion: `requested`/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); +}); + +test("initial orchestrate checks self-approval route access only when enabled", () => { + const accessPolicy = JSON.stringify({ + route_overrides: { + "agent-self-approve": ["MEMBER"], + }, + }); + const disabled = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + REPOSITORY_PRIVATE: "false", + ACCESS_POLICY: accessPolicy, + AGENT_ALLOW_SELF_APPROVE: "false", + }); + + assert.equal(disabled.status, 0, disabled.stderr || disabled.stdout); + assert.equal(disabled.outputs.get("decision"), "dispatch"); + assert.equal(disabled.outputs.get("next_action"), "implement"); + assert.match(disabled.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); + + const enabled = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + REPOSITORY_PRIVATE: "false", + ACCESS_POLICY: accessPolicy, + AGENT_ALLOW_SELF_APPROVE: "true", + }); + + assert.equal(enabled.status, 0, enabled.stderr || enabled.stdout); + assert.equal(enabled.outputs.get("decision"), "stop"); + assert.equal( + enabled.outputs.get("reason"), + "orchestrate requests require agent-self-approve access; agent-self-approve currently requires MEMBER access.", + ); + assert.doesNotMatch(enabled.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); +}); + +test("initial orchestrate checks self-merge route access only when enabled", () => { + const accessPolicy = JSON.stringify({ + route_overrides: { + "agent-self-merge": ["MEMBER"], + }, + }); + const disabled = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + REPOSITORY_PRIVATE: "false", + ACCESS_POLICY: accessPolicy, + AGENT_ALLOW_SELF_APPROVE: "true", + AGENT_ALLOW_SELF_MERGE: "false", + }); + + assert.equal(disabled.status, 0, disabled.stderr || disabled.stdout); + assert.equal(disabled.outputs.get("decision"), "dispatch"); + assert.equal(disabled.outputs.get("next_action"), "implement"); + + const enabled = runOrchestrateHandoff({ + TARGET_KIND: "issue", + TARGET_NUMBER: "20", + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + REPOSITORY_PRIVATE: "false", + ACCESS_POLICY: accessPolicy, + AGENT_ALLOW_SELF_APPROVE: "true", + AGENT_ALLOW_SELF_MERGE: "true", + }); + + assert.equal(enabled.status, 0, enabled.stderr || enabled.stdout); + assert.equal(enabled.outputs.get("decision"), "stop"); + assert.equal( + enabled.outputs.get("reason"), + "orchestrate requests require agent-self-merge access; agent-self-merge currently requires MEMBER access.", + ); + assert.doesNotMatch(enabled.ghLog, /actions\/workflows\/agent-implement\.yml\/dispatches/); +}); + +test("agent parent orchestrate stop posts final comment without follow-up", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "stop", + reason: "All child work is complete.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "agent planner stop: All child work is complete."); + assert.match(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /Sepo orchestration stopped after `orchestrate` concluded `done`\./); + assert.match(run.ghLog, /Source conclusion: `done`/); + assert.match(run.ghLog, /Target: `issue #76`/); + assert.match(run.ghLog, /Round: `2\/10`/); + assert.match(run.ghLog, /Reason: agent planner stop: All child work is complete\./); + assert.match(run.ghLog, /Source run ID: `parent-run-123`/); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.match(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("agent parent orchestrate blocked posts planner clarification", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "blocked", + reason: "Need maintainer input before choosing the next child.", + user_message: "I need a maintainer decision before continuing the orchestration.", + clarification_request: "Should the next child stack on PR #112 or wait for it to merge?", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal( + run.outputs.get("reason"), + "agent planner blocked: Need maintainer input before choosing the next child.", + ); + assert.match(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /Sepo orchestration needs clarification before it can continue\./); + assert.match(run.ghLog, /I need a maintainer decision before continuing the orchestration\./); + assert.match(run.ghLog, /Clarification request: Should the next child stack on PR #112 or wait for it to merge\?/); + assert.match(run.ghLog, /Reason: agent planner blocked: Need maintainer input before choosing the next child\./); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.match(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /Sepo orchestration stopped after/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("agent parent orchestrate blocked without message posts generic stop", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "blocked", + reason: "Context missing.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "agent planner blocked: Context missing."); + assert.match(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /Sepo orchestration stopped after `orchestrate` concluded `done`\./); + assert.match(run.ghLog, /Reason: agent planner blocked: Context missing\./); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.match(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /Sepo orchestration needs clarification before it can continue\./); + assert.doesNotMatch(run.ghLog, /Clarification request:/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("agent parent orchestrate stop skips matching trusted final comment", () => { + const existingStopBody = [ + "Sepo orchestration stopped after `orchestrate` concluded `done`.", + "", + "- Source action: `orchestrate`", + "- Source conclusion: `done`", + "- Target: `issue #76`", + "- Round: `2/10`", + "- Reason: agent planner stop: All child work is complete.", + "- Source run ID: `parent-run-123`", + "", + "No follow-up workflow was dispatched. Inspect the source action status comment and workflow logs before retrying or continuing manually.", + "", + "", + ].join("\n"); + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "existing-stop", + body: existingStopBody, + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + FAKE_PLANNER_RESPONSE: JSON.stringify({ + decision: "stop", + reason: "All child work is complete.", + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("heuristics parent orchestrate stops do not post final comments", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "issue", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "10", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "automation round budget exhausted"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("agent parent orchestrate stops for pull requests do not post final comments", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "done", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "76", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "2", + AUTOMATION_MAX_ROUNDS: "10", + SOURCE_RUN_ID: "parent-run-123", + FAKE_PR_STATE: "CLOSED", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "pull request is closed"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /actions\/workflows\//); + assert.equal(run.dispatchPayload, null); +}); + +test("terminal child result reports to parent and preserves terminal reruns", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: childBody, + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /Child task completed\./); + assert.match(run.ghLog, /\| Child task \| PR \| Outcome \| Parent round \| Next step \|/); + assert.match(run.ghLog, /\| #77 \| #88 \| Ready to ship \| 2 \/ 5 \| Resuming parent orchestration \|/); + assert.match(run.ghLog, /Summary: review verdict is SHIP/); + assert.match(run.ghLog, //); + assert.doesNotMatch(run.ghLog, //); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_action, "orchestrate"); + assert.equal(inputs.source_conclusion, "done"); + assert.equal(inputs.target_number, "76"); + assert.equal(inputs.automation_mode, "agent"); +}); + +test("terminal child result trusts app-authored issue body markers", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Closes #77", + FAKE_ISSUE_BODY: childBody, + FAKE_ISSUE_AUTHOR: "app/sepo-agent-app", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /issue edit 77 --repo self-evolving\/repo --body-file/); + assert.doesNotMatch(run.stderr, /Ignoring untrusted terminal sub-orchestrator marker/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_conclusion, "done"); + assert.equal(inputs.target_number, "76"); +}); + +test("terminal child ignores forged user-authored dispatched report markers", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: childBody, + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "forged-terminal-report", + body: "", + user: { login: "lolipopshock" }, + }, + ]), + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_conclusion, "done"); + assert.equal(inputs.target_number, "76"); +}); + +test("terminal child posts visible stop for user-authored child issue markers", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: childBody, + FAKE_ISSUE_AUTHOR: "lolipopshock", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/88\/comments/); + assert.match(run.ghLog, /Sepo could not report this terminal child result to the parent\./); + assert.match(run.ghLog, /\| #77 \| #88 \| #76 \| Issue body \| Stopped \|/); + assert.match(run.ghLog, /Reason: The child issue body marker was authored by `lolipopshock`/); + assert.match(run.ghLog, //); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.stderr, /Ignoring untrusted terminal sub-orchestrator marker in issue #77 body from lolipopshock/); +}); + +test("terminal child rejected-marker stop comments are deduped on rerun", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: childBody, + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "existing-terminal-stop", + body: [ + "Sepo could not report this terminal child result to the parent.", + "", + "", + ].join("\n"), + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/88\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.stderr, /Ignoring untrusted terminal sub-orchestrator marker in issue #77 body from lolipopshock/); +}); + +test("ordinary terminal PR stops skip visible sub-orchestration stop without child marker", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Closes #77", + FAKE_ISSUE_BODY: "Regular issue body without sub-orchestration metadata.", + FAKE_ISSUE_AUTHOR: "lolipopshock", + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.doesNotMatch(run.ghLog, /api --method POST repos\/self-evolving\/repo\/issues\/88\/comments/); + assert.doesNotMatch(run.ghLog, /sepo-sub-orchestrator-terminal-stop/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.doesNotMatch(run.stderr, /Ignoring untrusted terminal sub-orchestrator marker/); +}); + +test("terminal child ignores forged app-authored child marker comments", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: "User-authored child issue body.", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "forged-agent-output", + body: [ + "Answer summary from another route.", + "", + "", + ].join("\n"), + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.doesNotMatch(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); +}); + +test("terminal child reports from agent-authored adoption marker comments", () => { + const childMarker = [ + "Sepo adopted this issue as a sub-orchestrator child of #76.", + "", + "Stage: stage-1", + "Parent round: 2", + "", + "", + "", + ].join("\n"); + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "review", + SOURCE_CONCLUSION: "SHIP", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "88", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + FAKE_PR_BODY: "Implements #77", + FAKE_ISSUE_BODY: "User-authored child issue body.", + FAKE_ISSUE_AUTHOR: "lolipopshock", + FAKE_ISSUE_COMMENTS_JSON: JSON.stringify([ + { + id: "trusted-child-marker", + body: childMarker, + user: { login: "sepo-agent-app[bot]" }, + }, + ]), + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/comments\/trusted-child-marker/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_conclusion, "done"); + assert.equal(inputs.target_number, "76"); +}); + +test("terminal child round-budget stops report blocked to the parent", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "implement", + SOURCE_CONCLUSION: "success", + TARGET_KIND: "issue", + TARGET_NUMBER: "77", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "5", + AUTOMATION_MAX_ROUNDS: "5", + FAKE_ISSUE_BODY: childBody, + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("reason"), "automation round budget exhausted"); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + assert.match(run.ghLog, /Child task completed\./); + assert.match(run.ghLog, /\| Child task \| Outcome \| Parent round \| Next step \|/); + assert.match(run.ghLog, /\| #77 \| Blocked \| 2 \/ 5 \| Resuming parent orchestration \|/); + assert.match(run.ghLog, //); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_conclusion, "blocked"); + assert.equal(inputs.target_number, "76"); +}); + +test("terminal child invalid access policy reports failed to the parent", () => { + const childBody = ""; + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "requested", + TARGET_KIND: "issue", + TARGET_NUMBER: "77", + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "1", + ACCESS_POLICY: "{", + FAKE_ISSUE_BODY: childBody, + }); + + assert.equal(run.status, 0); + assert.equal(run.outputs.get("decision"), "stop"); + assert.match(run.outputs.get("reason") || "", /invalid AGENT_ACCESS_POLICY/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/76\/comments/); + assert.match(run.ghLog, /actions\/workflows\/agent-orchestrator\.yml\/dispatches/); + const inputs = run.dispatchPayload?.inputs as Record; + assert.equal(inputs.source_conclusion, "failed"); + assert.equal(inputs.target_number, "76"); +}); + +test("orchestrated fix-pr no_changes posts visible stop context without review handoff", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "fix-pr", + SOURCE_CONCLUSION: "no_changes", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "99", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "3", + SOURCE_RUN_ID: "fix-run-123", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.match(run.outputs.get("reason") || "", /fix-pr concluded no_changes/); + assert.match(run.outputs.get("reason") || "", /must succeed before re-review/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/99\/comments/); + assert.match(run.ghLog, /Source action: `fix-pr`/); + assert.match(run.ghLog, /Source conclusion: `no_changes`/); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-review\.yml\/dispatches/); +}); + +test("orchestrated implement no_changes posts visible stop context without review handoff", () => { + const run = runOrchestrateHandoff({ + SOURCE_ACTION: "implement", + SOURCE_CONCLUSION: "no_changes", + TARGET_KIND: "issue", + TARGET_NUMBER: "84", + AUTOMATION_MODE: "heuristics", + AUTOMATION_CURRENT_ROUND: "2", + SOURCE_RUN_ID: "implement-run-456", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("decision"), "stop"); + assert.equal(run.outputs.get("next_action"), ""); + assert.match(run.outputs.get("reason") || "", /implement concluded no_changes/); + assert.match(run.ghLog, /repos\/self-evolving\/repo\/issues\/84\/comments/); + assert.match(run.ghLog, /Source action: `implement`/); + assert.match(run.ghLog, /Source conclusion: `no_changes`/); + assert.match(run.ghLog, /Source run ID: `implement-run-456`/); + assert.match(run.ghLog, /No follow-up workflow was dispatched/); + assert.doesNotMatch(run.ghLog, /actions\/workflows\/agent-review\.yml\/dispatches/); +}); diff --git a/.agent/src/__tests__/orchestrator-preflight-cli.test.ts b/.agent/src/__tests__/orchestrator-preflight-cli.test.ts new file mode 100644 index 0000000..d7fd057 --- /dev/null +++ b/.agent/src/__tests__/orchestrator-preflight-cli.test.ts @@ -0,0 +1,162 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + return outputs; +} + +function runPreflight(env: Record): { + status: number | null; + stderr: string; + stdout: string; + outputs: Map; +} { + const tempDir = mkdtempSync(join(tmpdir(), "agent-orchestrator-preflight-")); + try { + const outputPath = join(tempDir, "github-output.txt"); + writeFileSync(outputPath, "", "utf8"); + const result = spawnSync("node", [".agent/dist/cli/orchestrator-preflight.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + AUTOMATION_MODE: "agent", + AUTOMATION_CURRENT_ROUND: "1", + AUTOMATION_MAX_ROUNDS: "5", + SOURCE_ACTION: "orchestrate", + SOURCE_CONCLUSION: "requested", + TARGET_KIND: "issue", + AUTHOR_ASSOCIATION: "MEMBER", + REPOSITORY_PRIVATE: "true", + ...env, + }, + encoding: "utf8", + }); + + return { + status: result.status, + stderr: result.stderr, + stdout: result.stdout, + outputs: parseGithubOutput(outputPath), + }; + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +} + +test("preflight disables planner when initial orchestrate lacks delegated route access", () => { + const run = runPreflight({ + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: JSON.stringify({ + route_overrides: { + implement: ["MEMBER"], + }, + }), + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("planner_enabled"), "false"); + assert.equal(run.outputs.get("authorization_stop"), "true"); + assert.equal( + run.outputs.get("authorization_stop_reason"), + "orchestrate requests require implement access; implement currently requires MEMBER access.", + ); +}); + +test("preflight keeps planner enabled for authorized issue meta-orchestration", () => { + const run = runPreflight({}); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("planner_enabled"), "true"); + assert.equal(run.outputs.get("authorization_stop"), "false"); +}); + +test("preflight defaults automation max rounds to 12", () => { + const run = runPreflight({ AUTOMATION_MAX_ROUNDS: "" }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("max_rounds"), "12"); + assert.equal(run.outputs.get("planner_enabled"), "true"); +}); + +test("preflight checks self-approval delegated access only when enabled", () => { + const accessPolicy = JSON.stringify({ + route_overrides: { + "agent-self-approve": ["MEMBER"], + }, + }); + const disabled = runPreflight({ + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: accessPolicy, + REPOSITORY_PRIVATE: "false", + AGENT_ALLOW_SELF_APPROVE: "false", + }); + assert.equal(disabled.status, 0, disabled.stderr || disabled.stdout); + assert.equal(disabled.outputs.get("authorization_stop"), "false"); + + const enabled = runPreflight({ + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: accessPolicy, + REPOSITORY_PRIVATE: "false", + AGENT_ALLOW_SELF_APPROVE: "true", + }); + assert.equal(enabled.status, 0, enabled.stderr || enabled.stdout); + assert.equal(enabled.outputs.get("authorization_stop"), "true"); + assert.equal( + enabled.outputs.get("authorization_stop_reason"), + "orchestrate requests require agent-self-approve access; agent-self-approve currently requires MEMBER access.", + ); +}); + +test("preflight checks self-merge delegated access only when enabled", () => { + const accessPolicy = JSON.stringify({ + route_overrides: { + "agent-self-merge": ["MEMBER"], + }, + }); + const disabled = runPreflight({ + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: accessPolicy, + REPOSITORY_PRIVATE: "false", + AGENT_ALLOW_SELF_APPROVE: "true", + AGENT_ALLOW_SELF_MERGE: "false", + }); + assert.equal(disabled.status, 0, disabled.stderr || disabled.stdout); + assert.equal(disabled.outputs.get("authorization_stop"), "false"); + + const enabled = runPreflight({ + AUTHOR_ASSOCIATION: "CONTRIBUTOR", + ACCESS_POLICY: accessPolicy, + REPOSITORY_PRIVATE: "false", + AGENT_ALLOW_SELF_APPROVE: "true", + AGENT_ALLOW_SELF_MERGE: "true", + }); + assert.equal(enabled.status, 0, enabled.stderr || enabled.stdout); + assert.equal(enabled.outputs.get("authorization_stop"), "true"); + assert.equal( + enabled.outputs.get("authorization_stop_reason"), + "orchestrate requests require agent-self-merge access; agent-self-merge currently requires MEMBER access.", + ); +}); + +test("preflight keeps planner enabled for authorized PR orchestration", () => { + const run = runPreflight({ + TARGET_KIND: "pull_request", + }); + + assert.equal(run.status, 0, run.stderr || run.stdout); + assert.equal(run.outputs.get("planner_enabled"), "true"); + assert.equal(run.outputs.get("authorization_stop"), "false"); +}); diff --git a/.agent/src/__tests__/pending-update-pr-gate-shell.test.ts b/.agent/src/__tests__/pending-update-pr-gate-shell.test.ts new file mode 100644 index 0000000..44d2696 --- /dev/null +++ b/.agent/src/__tests__/pending-update-pr-gate-shell.test.ts @@ -0,0 +1,116 @@ +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { spawnSync } from "node:child_process"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +function runPendingGate(prsJson: string, extraEnv: Record = {}) { + const tempDir = mkdtempSync(join(tmpdir(), "pending-update-gate-")); + const binDir = join(tempDir, "bin"); + const outputFile = join(tempDir, "outputs.txt"); + const responseFile = join(tempDir, "prs.json"); + const ghPath = join(binDir, "gh"); + mkdirSync(binDir); + writeFileSync(responseFile, prsJson); + writeFileSync( + ghPath, + [ + "#!/usr/bin/env bash", + "set -euo pipefail", + "if [ \"$1 $2 $3\" != \"pr list --repo\" ]; then", + " echo \"unexpected gh invocation: $*\" >&2", + " exit 1", + "fi", + "cat \"${GH_STUB_RESPONSE}\"", + ].join("\n") + "\n", + ); + chmodSync(ghPath, 0o755); + + const result = spawnSync("bash", ["scripts/resolve-pending-update-pr.sh"], { + cwd: process.cwd(), + env: { + ...process.env, + GH_TOKEN: "test-token", + GITHUB_OUTPUT: outputFile, + GITHUB_REPOSITORY: "self-evolving/repo", + GH_STUB_RESPONSE: responseFile, + IGNORE_EXISTING_UPDATE_PR: "false", + PATH: `${binDir}:${process.env.PATH || ""}`, + UPDATE_BRANCH_PREFIX: "agent/update-agent-infra-", + ...extraEnv, + }, + encoding: "utf8", + }); + const outputText = result.status === 0 ? readFileSync(outputFile, "utf8") : ""; + const payload = result.stdout.trim() ? JSON.parse(result.stdout) : null; + return { result, outputText, payload }; +} + +test("pending update PR gate adopts same-repository update branches", () => { + const { result, outputText, payload } = runPendingGate( + JSON.stringify([ + { + number: 123, + url: "https://github.com/self-evolving/repo/pull/123", + headRefName: "agent/update-agent-infra-20260503", + isCrossRepository: false, + }, + ]), + ); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, false); + assert.equal(payload.found, true); + assert.equal(payload.reason, "existing update PR will be updated"); + assert.equal(payload.prNumber, "123"); + assert.equal(payload.branch, "agent/update-agent-infra-20260503"); + assert.match(outputText, /skip<<[\s\S]*false/); + assert.match(outputText, /found<<[\s\S]*true/); + assert.match(outputText, /pr_url<<[\s\S]*\/pull\/123/); +}); + +test("pending update PR gate ignores unrelated and cross-repository PRs", () => { + const { result, payload } = runPendingGate( + JSON.stringify([ + { + number: 10, + url: "https://github.com/self-evolving/repo/pull/10", + headRefName: "agent/update-agent-infra-20260503", + isCrossRepository: true, + }, + { + number: 11, + url: "https://github.com/self-evolving/repo/pull/11", + headRefName: "agent/implement-issue-27/codex-1", + isCrossRepository: false, + }, + ]), + ); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, false); + assert.equal(payload.found, false); + assert.equal(payload.reason, "no pending update PR"); +}); + +test("pending update PR gate allows explicit force runs", () => { + const { result, payload } = runPendingGate( + JSON.stringify([ + { + number: 123, + url: "https://github.com/self-evolving/repo/pull/123", + headRefName: "agent/update-agent-infra-20260503", + isCrossRepository: false, + }, + ]), + { IGNORE_EXISTING_UPDATE_PR: "true" }, + ); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.skip, false); + assert.equal(payload.found, false); + assert.equal(payload.reason, "pending update PR override enabled"); + assert.equal(payload.prNumber, ""); + assert.equal(payload.branch, ""); +}); diff --git a/.agent/src/__tests__/post-comment-cli.test.ts b/.agent/src/__tests__/post-comment-cli.test.ts new file mode 100644 index 0000000..9568634 --- /dev/null +++ b/.agent/src/__tests__/post-comment-cli.test.ts @@ -0,0 +1,377 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): void { + writeFileSync(join(tempDir, "gh"), body, { encoding: "utf8", mode: 0o755 }); +} + +test("post-comment CLI still posts review comments when summary minimization fails", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + const responsePath = join(tempDir, "response.txt"); + writeFileSync(responsePath, "Review body\n", "utf8"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"errors":[{"message":"graphql unavailable"}]}\\n' + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "review", + RESPONSE_FILE: responsePath, + REQUESTED_BY: "lolipopshock", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match( + result.stderr, + /Failed to collapse previous AI review synthesis comments for self-evolving\/repo#321: gh api graphql returned errors: graphql unavailable/, + ); + + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^pr comment 321 --body ## AI Review Synthesis/m); + + const output = readFileSync(outputPath, "utf8"); + assert.match(output, /^comment_posted< { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + const responsePath = join(tempDir, "response.txt"); + writeFileSync(responsePath, "Review body\n", "utf8"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf 'unexpected minimization call\\n' >&2 + exit 1 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_COLLAPSE_OLD_REVIEWS: "false", + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "review", + RESPONSE_FILE: responsePath, + REQUESTED_BY: "lolipopshock", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.equal(result.stderr, ""); + + const log = readFileSync(logPath, "utf8"); + assert.doesNotMatch(log, /^api graphql /m); + assert.match(log, /^pr comment 321 --body ## AI Review Synthesis/m); + + const output = readFileSync(outputPath, "utf8"); + assert.match(output, /^comment_posted< { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + const responsePath = join(tempDir, "response.txt"); + writeFileSync(responsePath, "Review body\n", "utf8"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"headRefOid":"abc123"}\\n' + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_COLLAPSE_OLD_REVIEWS: "false", + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "review", + RESPONSE_FILE: responsePath, + REQUESTED_BY: "lolipopshock", + REVIEWED_HEAD_SHA: "abc123", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^pr view 321 --json headRefName,headRefOid,isCrossRepository,state --repo self-evolving\/repo/m); + assert.match(log, //); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-comment CLI omits reviewed head marker when PR head changed", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + const responsePath = join(tempDir, "response.txt"); + writeFileSync(responsePath, "Review body\n", "utf8"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"headRefOid":"def456"}\\n' + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_COLLAPSE_OLD_REVIEWS: "false", + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "review", + RESPONSE_FILE: responsePath, + REQUESTED_BY: "lolipopshock", + REVIEWED_HEAD_SHA: "abc123", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stderr, /head marker omitted because the PR head changed/); + const log = readFileSync(logPath, "utf8"); + assert.doesNotMatch(log, /sepo-agent-review-synthesis-head/); + assert.match(log, /^pr comment 321 --body ## AI Review Synthesis/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-comment CLI collapses previous fix-pr status comments", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const countPath = join(tempDir, "graphql-count.txt"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + const responsePath = join(tempDir, "response.json"); + writeFileSync(responsePath, '{"summary":"Updated tests."}\n', "utf8"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + count="$(cat "$FAKE_GH_COUNT" 2>/dev/null || printf '0')" + count="$((count + 1))" + printf '%s' "$count" > "$FAKE_GH_COUNT" + case "$count" in + 1) + printf '{"data":{"viewer":{"login":"sepo-agent"}}}\\n' + exit 0 + ;; + 2) + printf '{"data":{"repository":{"pullRequest":{"comments":{"nodes":[{"id":"old-fix","body":"**Sepo pushed fixes for this PR.** Branch: \`agent/fix\`.\\\\n\\\\n","isMinimized":false,"author":{"login":"sepo-agent"}}],"pageInfo":{"hasNextPage":false,"endCursor":null}}}}}}\\n' + exit 0 + ;; + 3) + printf '{"data":{"minimizeComment":{"minimizedComment":{"isMinimized":true}}}}\\n' + exit 0 + ;; + esac +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BRANCH: "agent/fix", + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "fix-pr", + STATUS: "success", + RESPONSE_FILE: responsePath, + REQUESTED_BY: "lolipopshock", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_COUNT: countPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /Collapsed 1 previous fix-pr status comment/); + + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /id=old-fix/); + assert.match(log, /^pr comment 321 --body \*\*Sepo pushed fixes for this PR\.\*\*/m); + assert.match(log, //); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-comment CLI routes unsupported fix-pr status through cleanup", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-comment-")); + + try { + const countPath = join(tempDir, "graphql-count.txt"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "github-output.txt"); + writeFileSync(outputPath, "", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + count="$(cat "$FAKE_GH_COUNT" 2>/dev/null || printf '0')" + count="$((count + 1))" + printf '%s' "$count" > "$FAKE_GH_COUNT" + case "$count" in + 1) + printf '{"data":{"viewer":{"login":"sepo-agent"}}}\\n' + exit 0 + ;; + 2) + printf '{"data":{"repository":{"pullRequest":{"comments":{"nodes":[{"id":"old-unsupported","body":"**Sepo could not update this PR automatically.**\\\\n\\\\nPR fix runs currently support open same-repository pull requests only.","isMinimized":false,"author":{"login":"sepo-agent"}}],"pageInfo":{"hasNextPage":false,"endCursor":null}}}}}}\\n' + exit 0 + ;; + 3) + printf '{"data":{"minimizeComment":{"minimizedComment":{"isMinimized":true}}}}\\n' + exit 0 + ;; + esac +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-comment.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + COMMENT_TARGET: "pr", + TARGET_NUMBER: "321", + ROUTE: "fix-pr", + STATUS: "unsupported", + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_OUTPUT: outputPath, + FAKE_GH_COUNT: countPath, + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /Collapsed 1 previous fix-pr status comment/); + + const log = readFileSync(logPath, "utf8"); + assert.match(log, /id=old-unsupported/); + assert.match(log, /^pr comment 321 --body \*\*Sepo could not update this PR automatically\.\*\*/m); + assert.match(log, //); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/post-project-management-summary-cli.test.ts b/.agent/src/__tests__/post-project-management-summary-cli.test.ts new file mode 100644 index 0000000..167e4d2 --- /dev/null +++ b/.agent/src/__tests__/post-project-management-summary-cli.test.ts @@ -0,0 +1,99 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): void { + writeFileSync(join(tempDir, "gh"), body, { encoding: "utf8", mode: 0o755 }); +} + +function runCli(tempDir: string, env: Record) { + return spawnSync("node", [".agent/dist/cli/post-project-management-summary.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + ...env, + }, + encoding: "utf8", + }); +} + +test("post project management summary writes the Actions step summary without discussion posting", () => { + const tempDir = mkdtempSync(join(tmpdir(), "project-summary-")); + + try { + const bodyFile = join(tempDir, "summary.md"); + const stepSummary = join(tempDir, "step-summary.md"); + const outputs = join(tempDir, "outputs.txt"); + writeFileSync(bodyFile, "## Project Management Summary\n\n- Mode: dry run\n"); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_POST_SUMMARY: "false", + BODY_FILE: bodyFile, + GITHUB_OUTPUT: outputs, + GITHUB_STEP_SUMMARY: stepSummary, + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /posting is disabled/); + assert.match(readFileSync(stepSummary, "utf8"), /Mode: dry run/); + assert.match(readFileSync(outputs, "utf8"), /summary_posted<<.*\nfalse\n/s); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post project management summary comments on today's Daily Summary discussion when enabled", () => { + const tempDir = mkdtempSync(join(tmpdir(), "project-summary-")); + + try { + const bodyFile = join(tempDir, "summary.md"); + const logPath = join(tempDir, "gh.log"); + const outputPath = join(tempDir, "outputs.txt"); + const stepSummary = join(tempDir, "step-summary.md"); + writeFileSync(bodyFile, "## Project Management Summary\n\n- Mode: labels applied\n"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + if printf '%s\n' "$*" | grep -q 'discussions(first'; then + printf '{"data":{"repository":{"discussions":{"nodes":[{"id":"D_1","number":7,"title":"Daily Summary — 2026-04-29","url":"https://github.com/self-evolving/repo/discussions/7","category":{"name":"General"}}]}}}}' + exit 0 + fi + if printf '%s\n' "$*" | grep -q 'addDiscussionComment'; then + printf '{"data":{"addDiscussionComment":{"comment":{"url":"https://github.com/self-evolving/repo/discussions/7#discussioncomment-1"}}}}' + exit 0 + fi +fi +printf 'unexpected gh args: %s\n' "$*" >&2 +exit 1 +`, + ); + + const result = runCli(tempDir, { + AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY: "General", + AGENT_PROJECT_MANAGEMENT_POST_SUMMARY: "true", + AGENT_PROJECT_MANAGEMENT_SUMMARY_DATE: "2026-04-29", + BODY_FILE: bodyFile, + FAKE_GH_LOG: logPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + GITHUB_STEP_SUMMARY: stepSummary, + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Posted project management summary to https:\/\/github\.com\/self-evolving\/repo\/discussions\/7/); + + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /addDiscussionComment/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/post-response-cli.test.ts b/.agent/src/__tests__/post-response-cli.test.ts new file mode 100644 index 0000000..b413363 --- /dev/null +++ b/.agent/src/__tests__/post-response-cli.test.ts @@ -0,0 +1,336 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function writeFakeGh(tempDir: string, body: string): void { + writeFileSync(join(tempDir, "gh"), body, { encoding: "utf8", mode: 0o755 }); +} + +test("post-response CLI still posts rubrics reviews when minimization fails", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "## Rubrics Review\n\nbody\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"errors":[{"message":"graphql unavailable"}]}\\n' + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match( + result.stderr, + /Failed to collapse previous rubrics review comments for self-evolving\/repo#321: gh api graphql returned errors: graphql unavailable/, + ); + + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^pr comment 321 --body ## Rubrics Review/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-response CLI skips rubrics review minimization when disabled", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "## Rubrics Review\n\nbody\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf 'unexpected minimization call\\n' >&2 + exit 1 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_COLLAPSE_OLD_REVIEWS: "false", + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.equal(result.stderr, ""); + + const log = readFileSync(logPath, "utf8"); + assert.doesNotMatch(log, /^api graphql /m); + assert.match(log, /^pr comment 321 --body ## Rubrics Review/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-response CLI updates latest Sepo self-approval marker comment", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "Sepo self-approval completed.\n\n\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app[bot]"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":111,"body":"old self marker\\\\n","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}},{"id":222,"body":"untrusted marker\\\\n","created_at":"2026-05-07T10:05:00Z","user":{"login":"alice"}},{"id":333,"body":"latest self marker\\\\n","created_at":"2026-05-07T10:10:00Z","user":{"login":"app/sepo-agent-app"}}]]\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--method" ] && [ "$3" = "PATCH" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Updated self-approval status comment/); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^api --paginate --slurp repos\/self-evolving\/repo\/issues\/321\/comments/m); + assert.match(log, /^api --method PATCH repos\/self-evolving\/repo\/issues\/comments\/333 /m); + assert.doesNotMatch(log, /issues\/comments\/111/); + assert.doesNotMatch(log, /issues\/comments\/222/); + assert.doesNotMatch(log, /^pr comment /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-response CLI updates latest Sepo self-merge marker comment", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "Sepo self-merge completed.\n\n\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app[bot]"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":111,"body":"old merge marker\\\\n","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}},{"id":222,"body":"untrusted merge marker\\\\n","created_at":"2026-05-07T10:05:00Z","user":{"login":"alice"}},{"id":333,"body":"latest merge marker\\\\n","created_at":"2026-05-07T10:10:00Z","user":{"login":"app/sepo-agent-app"}}]]\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--method" ] && [ "$3" = "PATCH" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Updated self-merge status comment/); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^api --paginate --slurp repos\/self-evolving\/repo\/issues\/321\/comments/m); + assert.match(log, /^api --method PATCH repos\/self-evolving\/repo\/issues\/comments\/333 /m); + assert.doesNotMatch(log, /issues\/comments\/111/); + assert.doesNotMatch(log, /issues\/comments\/222/); + assert.doesNotMatch(log, /^pr comment /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-response CLI ignores untrusted self-approval marker comments", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "Sepo self-approval completed.\n\n\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":456,"body":"user marker\\\\n","created_at":"2026-05-07T10:00:00Z","user":{"login":"someone-else"}}]]\\n' + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Created self-approval status comment/); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^api --paginate --slurp repos\/self-evolving\/repo\/issues\/321\/comments/m); + assert.doesNotMatch(log, /^api --method PATCH /m); + assert.match(log, /^pr comment 321 --body Sepo self-approval completed/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("post-response CLI does not fallback post when self-approval upsert fails", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-post-response-")); + + try { + const logPath = join(tempDir, "gh.log"); + const bodyPath = join(tempDir, "body.md"); + writeFileSync(bodyPath, "Sepo self-approval completed.\n\n\n", "utf8"); + writeFakeGh( + tempDir, + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":789,"body":"existing marker\\\\n","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}}]]\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--method" ] && [ "$3" = "PATCH" ]; then + printf 'patch unavailable\\n' >&2 + exit 1 +fi +if [ "$1" = "pr" ] && [ "$2" = "comment" ]; then + printf 'unexpected fallback post\\n' >&2 + exit 1 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, + ); + + const result = spawnSync("node", [".agent/dist/cli/post-response.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + BODY_FILE: bodyPath, + RESPONSE_KIND: "pr_comment", + TARGET_NUMBER: "321", + GITHUB_REPOSITORY: "self-evolving/repo", + FAKE_GH_LOG: logPath, + }, + encoding: "utf8", + }); + + assert.equal(result.status, 1); + assert.match( + result.stderr, + /Failed to upsert self-approval status comment for self-evolving\/repo#321:/, + ); + const log = readFileSync(logPath, "utf8"); + assert.match(log, /^api graphql /m); + assert.match(log, /^api --paginate --slurp repos\/self-evolving\/repo\/issues\/321\/comments/m); + assert.match(log, /^api --method PATCH repos\/self-evolving\/repo\/issues\/comments\/789 /m); + assert.doesNotMatch(log, /^pr comment /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/prepare-release-cli.test.ts b/.agent/src/__tests__/prepare-release-cli.test.ts new file mode 100644 index 0000000..7814880 --- /dev/null +++ b/.agent/src/__tests__/prepare-release-cli.test.ts @@ -0,0 +1,169 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + return outputs; +} + +test("prepare-release reuses an open release issue for the same version", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-prepare-release-")); + try { + const outputPath = join(tempDir, "github-output.txt"); + const callsPath = join(tempDir, "gh-calls.txt"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync(callsPath, "", "utf8"); + writeFileSync( + join(tempDir, "gh"), + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$GH_CALLS" +if [ "$1" = "issue" ] && [ "$2" = "list" ]; then + printf '[{"number":42,"title":"Prepare Sepo release 0.2.0","url":"https://github.com/self-evolving/repo/issues/42"}]\\n' + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "create" ]; then + echo "unexpected create" >&2 + exit 1 +fi +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/prepare-release.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GH_CALLS: callsPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + RUNNER_TEMP: tempDir, + VERSION: "0.2.0", + }, + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("issue_number"), "42"); + assert.equal(outputs.get("issue_action"), "reused"); + assert.equal(outputs.get("version"), "0.2.0"); + assert.match(outputs.get("request_text") || "", /0\.2\.0/); + + const calls = readFileSync(callsPath, "utf8"); + assert.match(calls, /issue list/); + assert.doesNotMatch(calls, /issue create/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-release emits created issue outputs from a valid create URL", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-prepare-release-")); + try { + const outputPath = join(tempDir, "github-output.txt"); + const callsPath = join(tempDir, "gh-calls.txt"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync(callsPath, "", "utf8"); + writeFileSync( + join(tempDir, "gh"), + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$GH_CALLS" +if [ "$1" = "issue" ] && [ "$2" = "list" ]; then + printf '[]\\n' + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "create" ]; then + printf 'https://github.com/self-evolving/repo/issues/77\\n' + exit 0 +fi +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/prepare-release.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GH_CALLS: callsPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + RUNNER_TEMP: tempDir, + VERSION: "0.2.0", + }, + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("issue_number"), "77"); + assert.equal(outputs.get("issue_action"), "created"); + assert.equal(outputs.get("issue_url"), "https://github.com/self-evolving/repo/issues/77"); + + const bodyFile = readdirSync(tempDir).find((name) => /^release-prepare-[a-f0-9]+\.md$/.test(name)); + assert.ok(bodyFile); + const issueBody = readFileSync(join(tempDir, bodyFile), "utf8"); + assert.match(issueBody, /`\.agent\/CHANGELOG\.md`/); + + const calls = readFileSync(callsPath, "utf8"); + assert.match(calls, /issue create/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-release fails clearly when a created issue URL has no issue number", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-prepare-release-")); + try { + const outputPath = join(tempDir, "github-output.txt"); + const callsPath = join(tempDir, "gh-calls.txt"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync(callsPath, "", "utf8"); + writeFileSync( + join(tempDir, "gh"), + `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$GH_CALLS" +if [ "$1" = "issue" ] && [ "$2" = "list" ]; then + printf '[]\\n' + exit 0 +fi +if [ "$1" = "issue" ] && [ "$2" = "create" ]; then + printf 'https://github.com/self-evolving/repo/issues/not-a-number\\n' + exit 0 +fi +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + const result = spawnSync("node", [".agent/dist/cli/prepare-release.js"], { + cwd: repoRoot, + encoding: "utf8", + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + GH_CALLS: callsPath, + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + RUNNER_TEMP: tempDir, + VERSION: "0.2.0", + }, + }); + + assert.equal(result.status, 1); + assert.match(result.stderr, /Could not parse created release prepare issue number/); + assert.equal(readFileSync(outputPath, "utf8"), ""); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/prepare-self-approve-cli.test.ts b/.agent/src/__tests__/prepare-self-approve-cli.test.ts new file mode 100644 index 0000000..3003ff5 --- /dev/null +++ b/.agent/src/__tests__/prepare-self-approve-cli.test.ts @@ -0,0 +1,220 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function runPrepareSelfApprove(env: Record, tempDir: string): { + status: number | null; + output: string; + stderr: string; +} { + const outputFile = join(tempDir, "github-output"); + writeFileSync(outputFile, "", "utf8"); + const result = spawnSync("node", [".agent/dist/cli/prepare-self-approve.js"], { + cwd: repoRoot, + env: { + ...process.env, + ...env, + GITHUB_OUTPUT: outputFile, + }, + encoding: "utf8", + }); + return { + status: result.status, + output: readFileSync(outputFile, "utf8"), + stderr: result.stderr, + }; +} + +test("prepare-self-approve stops when self-approval is disabled", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const result = runPrepareSelfApprove({ + AGENT_ALLOW_SELF_APPROVE: "false", + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\nfalse/); + assert.match(result.output, /AGENT_ALLOW_SELF_APPROVE is not enabled/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-self-approve stops on non-PR targets before reading GitHub", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const result = runPrepareSelfApprove({ + AGENT_ALLOW_SELF_APPROVE: "true", + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "issue", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\nfalse/); + assert.match(result.output, /only supported for pull requests/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-self-approve stops on closed pull requests", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const logPath = join(tempDir, "gh.log"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"headRefName":"agent/test","headRefOid":"abc123","isCrossRepository":false,"state":"CLOSED"}\\n' + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = runPrepareSelfApprove({ + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_APPROVE: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\nfalse/); + assert.match(result.output, /pull request is closed/); + assert.match(readFileSync(logPath, "utf8"), /^pr view 42 /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-self-approve emits success outputs for trusted current-head SHIP", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const logPath = join(tempDir, "gh.log"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"author":{"login":"lolipopshock"},"headRefName":"agent/test","headRefOid":"abc123","isCrossRepository":false,"state":"OPEN"}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":123,"body":"## AI Review Synthesis ## Final Verdict SHIP","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}}]]\\n' + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = runPrepareSelfApprove({ + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_APPROVE: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\ntrue/); + assert.match(result.output, /head_sha<<[^\n]+\nabc123/); + assert.match(readFileSync(logPath, "utf8"), /^api graphql /m); + assert.match(readFileSync(logPath, "utf8"), /^api --paginate --slurp repos\/self-evolving\/repo\/issues\/42\/comments/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-self-approve runs non-SHIP HUMAN_DECISION gate", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const logPath = join(tempDir, "gh.log"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"author":{"login":"lolipopshock"},"headRefName":"agent/test","headRefOid":"abc123","isCrossRepository":false,"state":"OPEN"}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":123,"body":"## AI Review Synthesis ## Recommended Next Step HUMAN_DECISION ## Final Verdict NEEDS_REWORK","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}}]]\\n' + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = runPrepareSelfApprove({ + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_APPROVE: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + SOURCE_RECOMMENDED_NEXT_STEP: "HUMAN_DECISION", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\ntrue/); + assert.match(result.output, /head_sha<<[^\n]+\nabc123/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("prepare-self-approve requires trusted HUMAN_DECISION before non-SHIP gate", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-prepare-")); + try { + const logPath = join(tempDir, "gh.log"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + printf '{"author":{"login":"lolipopshock"},"headRefName":"agent/test","headRefOid":"abc123","isCrossRepository":false,"state":"OPEN"}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":123,"body":"## AI Review Synthesis ## Recommended Next Step FIX_PR ## Final Verdict NEEDS_REWORK","created_at":"2026-05-07T10:00:00Z","user":{"login":"sepo-agent-app"}}]]\\n' + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + + const result = runPrepareSelfApprove({ + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_APPROVE: "true", + FAKE_GH_LOG: logPath, + GITHUB_REPOSITORY: "self-evolving/repo", + SOURCE_RECOMMENDED_NEXT_STEP: "HUMAN_DECISION", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /should_run<<[^\n]+\nfalse/); + assert.match(result.output, /not SHIP/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/project-management-labels.test.ts b/.agent/src/__tests__/project-management-labels.test.ts new file mode 100644 index 0000000..0cf9858 --- /dev/null +++ b/.agent/src/__tests__/project-management-labels.test.ts @@ -0,0 +1,57 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { parseManagedLabelPlan } from "../project-management-labels.js"; + +test("managed label plan keeps only allowed project-management labels", () => { + const plan = parseManagedLabelPlan(` +## Project Management Summary + +\`\`\`json +{ + "label_changes": [ + { + "kind": "issue", + "number": 34, + "add": ["priority/p1", "bug", "effort/high"], + "remove": ["priority/p3", "external"] + }, + { + "kind": "discussion", + "number": 7, + "add": ["priority/p0"], + "remove": [] + } + ], + "comments": [{"body": "not allowed"}] +} +\`\`\` +`); + + assert.deepEqual(plan, { + valid: true, + label_changes: [ + { + kind: "issue", + number: 34, + add: ["priority/p1", "effort/high"], + remove: ["priority/p3"], + }, + ], + }); +}); + +test("managed label plan distinguishes malformed and missing json plans", () => { + assert.deepEqual(parseManagedLabelPlan("## Summary\n\nNo structured plan."), { + label_changes: [], + valid: false, + }); + assert.deepEqual(parseManagedLabelPlan("```json\nnot-json\n```"), { + label_changes: [], + valid: false, + }); + assert.deepEqual(parseManagedLabelPlan("```json\n{\"label_changes\":[]}\n```"), { + label_changes: [], + valid: true, + }); +}); diff --git a/.agent/src/__tests__/prompt-continuation.test.ts b/.agent/src/__tests__/prompt-continuation.test.ts new file mode 100644 index 0000000..9fd428b --- /dev/null +++ b/.agent/src/__tests__/prompt-continuation.test.ts @@ -0,0 +1,81 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { selectPromptForSessionOutcome } from "../acpx-adapter.js"; +import { + buildContinuationPrompt, + selectContinuationPromptForResume, + shouldReplayFullPromptOnResume, +} from "../prompt-continuation.js"; + +test("continuation prompt preserves latest trigger metadata and request text", () => { + const prompt = buildContinuationPrompt({ + REQUEST_SOURCE_KIND: "pull_request_review", + REQUEST_COMMENT_ID: "12345", + REQUEST_COMMENT_URL: "https://github.com/self-evolving/repo/pull/77#pullrequestreview-12345", + REQUEST_TEXT: "@sepo-agent /fix-pr", + }); + + assert.match(prompt, /Triggering source kind: `pull_request_review`/); + assert.match(prompt, /Triggering comment\/review ID: `12345`/); + assert.match(prompt, /@sepo-agent \/fix-pr/); +}); + +test("resumed orchestrated fix-pr replays the full route prompt", () => { + const promptVars = { + REQUEST_SOURCE_KIND: "workflow_dispatch", + REQUEST_TEXT: "@sepo-agent /orchestrate", + ORCHESTRATOR_CONTEXT: + "Address review synthesis: validate marker source, correct docs, classify terminal states.", + }; + const continuationPrompt = buildContinuationPrompt(promptVars); + const selectedContinuationPrompt = selectContinuationPromptForResume({ + route: "fix-pr", + promptVars, + continuationPrompt, + }); + + assert.equal(shouldReplayFullPromptOnResume("fix-pr", promptVars), true); + assert.equal(selectedContinuationPrompt, undefined); + + const agentFacingPrompt = selectPromptForSessionOutcome({ + fullPrompt: + "Full fix-pr prompt\nOrchestrator handoff context:\n" + + promptVars.ORCHESTRATOR_CONTEXT, + continuationPrompt: selectedContinuationPrompt, + outcome: { kind: "resumed", resumedFromSessionId: "ses-pr-77" }, + }); + + assert.match(agentFacingPrompt, /validate marker source/); + assert.match(agentFacingPrompt, /classify terminal states/); + assert.notEqual(agentFacingPrompt, continuationPrompt); +}); + +test("direct fix-pr resumes still use the lightweight continuation prompt", () => { + const promptVars = { + REQUEST_SOURCE_KIND: "issue_comment", + REQUEST_TEXT: "@sepo-agent /fix-pr please address the latest comment", + ORCHESTRATOR_CONTEXT: "", + }; + const continuationPrompt = buildContinuationPrompt(promptVars); + + assert.equal(shouldReplayFullPromptOnResume("fix-pr", promptVars), false); + assert.equal( + selectContinuationPromptForResume({ route: "fix-pr", promptVars, continuationPrompt }), + continuationPrompt, + ); +}); + +test("non-fix-pr routes keep continuation prompts even with supplemental context", () => { + const promptVars = { + REQUEST_TEXT: "@sepo-agent /review", + ORCHESTRATOR_CONTEXT: "Review the fix after the automated branch update.", + }; + const continuationPrompt = buildContinuationPrompt(promptVars); + + assert.equal(shouldReplayFullPromptOnResume("review", promptVars), false); + assert.equal( + selectContinuationPromptForResume({ route: "review", promptVars, continuationPrompt }), + continuationPrompt, + ); +}); diff --git a/.agent/src/__tests__/release-version.test.ts b/.agent/src/__tests__/release-version.test.ts new file mode 100644 index 0000000..9697aa1 --- /dev/null +++ b/.agent/src/__tests__/release-version.test.ts @@ -0,0 +1,20 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { parseReleaseVersion } from "../release-version.js"; + +test("parseReleaseVersion accepts plain SemVer and optional v prefix", () => { + assert.deepEqual(parseReleaseVersion("0.2.0"), { + version: "0.2.0", + tag: "v0.2.0", + major: 0, + minor: 2, + patch: 0, + prereleaseLabel: "", + }); + assert.equal(parseReleaseVersion("v1.0.0-rc.1").version, "1.0.0-rc.1"); +}); + +test("parseReleaseVersion rejects build metadata and leading zero prerelease numbers", () => { + assert.throws(() => parseReleaseVersion("1.0.0+build.1"), /version must be SemVer/); + assert.throws(() => parseReleaseVersion("1.0.0-rc.01"), /version must be SemVer/); +}); diff --git a/.agent/src/__tests__/resolve-agent-provider.test.ts b/.agent/src/__tests__/resolve-agent-provider.test.ts new file mode 100644 index 0000000..3a2a629 --- /dev/null +++ b/.agent/src/__tests__/resolve-agent-provider.test.ts @@ -0,0 +1,156 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = path.resolve(__dirname, "../../.."); +const resolverScript = path.join( + repoRoot, + ".github/actions/resolve-agent-provider/resolve-provider.sh", +); + +type ResolverEnv = Partial>; + +function parseOutputs(outputFile: string): Record { + if (!existsSync(outputFile)) { + return {}; + } + + return Object.fromEntries( + readFileSync(outputFile, "utf8") + .split(/\r?\n/) + .filter(Boolean) + .map((line) => { + const separator = line.indexOf("="); + assert.notEqual(separator, -1, `Expected GitHub output line with '=': ${line}`); + return [line.slice(0, separator), line.slice(separator + 1)]; + }), + ); +} + +function runResolver(env: ResolverEnv = {}) { + const tempDir = mkdtempSync(path.join(tmpdir(), "agent-provider-")); + const outputFile = path.join(tempDir, "github-output"); + + try { + const result = spawnSync("bash", [resolverScript], { + encoding: "utf8", + env: { + ...process.env, + GITHUB_OUTPUT: outputFile, + ROUTE: "test-route", + ROUTE_PROVIDER: "", + DEFAULT_PROVIDER: "auto", + OPENAI_API_KEY: "", + CLAUDE_CODE_OAUTH_TOKEN: "", + REQUIRED: "true", + ...env, + }, + }); + + return { + ...result, + outputs: parseOutputs(outputFile), + }; + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +} + +test("provider resolver auto-detects configured providers deterministically", () => { + const both = runResolver({ + OPENAI_API_KEY: "openai-token", + CLAUDE_CODE_OAUTH_TOKEN: "claude-token", + }); + + assert.equal(both.status, 0, both.stderr); + assert.equal(both.outputs.provider, "codex"); + assert.equal(both.outputs.reason, "OPENAI_API_KEY is configured"); + assert.equal(both.outputs.install_codex, "true"); + assert.equal(both.outputs.install_claude, "false"); + + const claudeOnly = runResolver({ CLAUDE_CODE_OAUTH_TOKEN: "claude-token" }); + + assert.equal(claudeOnly.status, 0, claudeOnly.stderr); + assert.equal(claudeOnly.outputs.provider, "claude"); + assert.equal(claudeOnly.outputs.reason, "CLAUDE_CODE_OAUTH_TOKEN is configured"); + assert.equal(claudeOnly.outputs.install_codex, "false"); + assert.equal(claudeOnly.outputs.install_claude, "true"); +}); + +test("provider resolver honors default and inline route overrides", () => { + const defaultOverride = runResolver({ + DEFAULT_PROVIDER: " Claude ", + OPENAI_API_KEY: "openai-token", + CLAUDE_CODE_OAUTH_TOKEN: "claude-token", + }); + + assert.equal(defaultOverride.status, 0, defaultOverride.stderr); + assert.equal(defaultOverride.outputs.provider, "claude"); + assert.equal(defaultOverride.outputs.reason, "AGENT_DEFAULT_PROVIDER"); + + const routeOverride = runResolver({ + ROUTE_PROVIDER: "codex", + DEFAULT_PROVIDER: "claude", + OPENAI_API_KEY: "openai-token", + CLAUDE_CODE_OAUTH_TOKEN: "claude-token", + }); + + assert.equal(routeOverride.status, 0, routeOverride.stderr); + assert.equal(routeOverride.outputs.provider, "codex"); + assert.equal(routeOverride.outputs.reason, "route override for test-route"); +}); + +test("provider resolver supports explicit providers without repository secrets", () => { + const codex = runResolver({ DEFAULT_PROVIDER: "codex" }); + + assert.equal(codex.status, 0, codex.stderr); + assert.equal(codex.outputs.provider, "codex"); + assert.equal(codex.outputs.reason, "AGENT_DEFAULT_PROVIDER"); + assert.equal(codex.outputs.install_codex, "true"); + assert.equal(codex.outputs.install_claude, "false"); + assert.match(codex.stderr, /relying on local Codex authentication/); + + const claude = runResolver({ ROUTE_PROVIDER: "claude", DEFAULT_PROVIDER: "codex" }); + + assert.equal(claude.status, 0, claude.stderr); + assert.equal(claude.outputs.provider, "claude"); + assert.equal(claude.outputs.reason, "route override for test-route"); + assert.equal(claude.outputs.install_codex, "false"); + assert.equal(claude.outputs.install_claude, "true"); + assert.match(claude.stderr, /relying on local Claude authentication/); +}); + +test("provider resolver supports nonfatal unresolved setup passes", () => { + const soft = runResolver({ REQUIRED: "false" }); + + assert.equal(soft.status, 0, soft.stderr); + assert.equal(soft.outputs.provider, ""); + assert.equal(soft.outputs.reason, "no configured provider"); + assert.equal(soft.outputs.install_codex, "false"); + assert.equal(soft.outputs.install_claude, "false"); + assert.match(soft.stderr, /No configured agent provider/); + assert.match(soft.stdout, /unresolved/); +}); + +test("provider resolver rejects invalid providers and required auto without readiness", () => { + const invalid = runResolver({ DEFAULT_PROVIDER: "co dex", OPENAI_API_KEY: "openai-token" }); + + assert.notEqual(invalid.status, 0); + assert.match(invalid.stderr, /Invalid agent provider 'co dex'/); + + const missingAuto = runResolver(); + + assert.notEqual(missingAuto.status, 0); + assert.match(missingAuto.stderr, /No configured agent provider/); +}); diff --git a/.agent/src/__tests__/resolve-approval-cli.test.ts b/.agent/src/__tests__/resolve-approval-cli.test.ts new file mode 100644 index 0000000..2f0a7eb --- /dev/null +++ b/.agent/src/__tests__/resolve-approval-cli.test.ts @@ -0,0 +1,293 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { buildApprovalRequestMarker } from "../approval.js"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + + return outputs; +} + +test("resolve-approval skips agent-managed approval request comments", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-approval-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + const marker = buildApprovalRequestMarker({ + request_id: "req-a1b2c3", + route: "implement", + target_kind: "issue", + target_number: 138, + }); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "githubuser", type: "User" }, + comment: { + id: 101, + node_id: "IC_101", + body: [ + "I triaged this as an `implement` request.", + "", + "```text", + "@sepo-agent /approve req-a1b2c3", + "```", + "", + marker, + ].join("\n"), + author_association: "MEMBER", + user: { login: "githubuser" }, + }, + issue: { + number: 138, + html_url: "https://github.com/self-evolving/repo/issues/138", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + execFileSync("node", [".agent/dist/cli/resolve-approval.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_dispatch"), "false"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-approval reports invalid AGENT_ACCESS_POLICY cleanly", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-approval-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + comment: { + id: 102, + node_id: "IC_102", + body: "@sepo-agent /approve req-a1b2c3", + author_association: "MEMBER", + user: { login: "alice" }, + }, + issue: { + number: 138, + html_url: "https://github.com/self-evolving/repo/issues/138", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + + const result = spawnSync("node", [".agent/dist/cli/resolve-approval.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + ACCESS_POLICY: "{", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 2); + assert.match(result.stderr, /Invalid AGENT_ACCESS_POLICY:/); + assert.doesNotMatch(result.stderr, /at parseAccessPolicy/); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_dispatch"), "false"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-approval applies access policy to the pending request route", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-approval-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + const marker = buildApprovalRequestMarker({ + request_id: "req-a1b2c3", + route: "implement", + target_kind: "issue", + target_number: 138, + target_url: "https://github.com/self-evolving/repo/issues/138", + workflow: "agent-implement.yml", + request_text: "please implement this", + }); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + repository: { private: true }, + comment: { + id: 102, + node_id: "IC_102", + body: "@sepo-agent /approve req-a1b2c3", + author_association: "CONTRIBUTOR", + user: { login: "alice" }, + }, + issue: { + number: 138, + html_url: "https://github.com/self-evolving/repo/issues/138", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + `#!/usr/bin/env bash +if [ "$1" = "api" ]; then + printf '[{"id":201,"created_at":"2026-04-23T00:00:00Z","body":%s}]\\n' "$(node -e 'process.stdout.write(JSON.stringify(process.env.MARKER_BODY))')" + exit 0 +fi +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/resolve-approval.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + MARKER_BODY: `Approval request\n\n${marker}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + ACCESS_POLICY: JSON.stringify({ + allowed_associations: ["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR"], + route_overrides: { + implement: ["OWNER", "MEMBER"], + }, + }), + REPOSITORY_PRIVATE: "true", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_dispatch"), "false"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-approval permits route approvals allowed by access policy", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-approval-")); + + try { + const eventPath = join(tempDir, "event.json"); + const outputPath = join(tempDir, "github-output.txt"); + const fakeGh = join(tempDir, "gh"); + const marker = buildApprovalRequestMarker({ + request_id: "req-d4e5f6", + route: "implement", + target_kind: "issue", + target_number: 139, + target_url: "https://github.com/self-evolving/repo/issues/139", + workflow: "agent-implement.yml", + request_text: "please implement this", + }); + + writeFileSync( + eventPath, + JSON.stringify({ + sender: { login: "alice", type: "User" }, + repository: { private: true }, + comment: { + id: 103, + node_id: "IC_103", + body: "@sepo-agent /approve req-d4e5f6", + author_association: "MEMBER", + user: { login: "alice" }, + }, + issue: { + number: 139, + html_url: "https://github.com/self-evolving/repo/issues/139", + }, + }), + "utf8", + ); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + fakeGh, + `#!/usr/bin/env bash +if [ "$1" = "api" ]; then + printf '[{"id":202,"created_at":"2026-04-23T00:00:00Z","body":%s}]\\n' "$(node -e 'process.stdout.write(JSON.stringify(process.env.MARKER_BODY))')" + exit 0 +fi +exit 1 +`, + { encoding: "utf8", mode: 0o755 }, + ); + + execFileSync("node", [".agent/dist/cli/resolve-approval.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + MARKER_BODY: `Approval request\n\n${marker}`, + GITHUB_EVENT_PATH: eventPath, + GITHUB_EVENT_NAME: "issue_comment", + GITHUB_OUTPUT: outputPath, + GITHUB_REPOSITORY: "self-evolving/repo", + INPUT_MENTION: "@sepo-agent", + ACCESS_POLICY: JSON.stringify({ + route_overrides: { + implement: ["OWNER", "MEMBER"], + }, + }), + REPOSITORY_PRIVATE: "true", + }, + stdio: "pipe", + }); + + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("should_dispatch"), "true"); + assert.equal(outputs.get("route"), "implement"); + assert.equal(outputs.get("workflow"), "agent-implement.yml"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/resolve-dispatch-cli.test.ts b/.agent/src/__tests__/resolve-dispatch-cli.test.ts new file mode 100644 index 0000000..2b8f5d4 --- /dev/null +++ b/.agent/src/__tests__/resolve-dispatch-cli.test.ts @@ -0,0 +1,174 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(path: string): Map { + const raw = readFileSync(path, "utf8"); + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + + return outputs; +} + +test("resolve-dispatch reports invalid AGENT_ACCESS_POLICY cleanly", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-dispatch-")); + + try { + const outputPath = join(tempDir, "github-output.txt"); + writeFileSync(outputPath, "", "utf8"); + + const result = spawnSync("node", [".agent/dist/cli/resolve-dispatch.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + REQUESTED_ROUTE: "answer", + REQUEST_TEXT: "@sepo-agent /answer please check this", + TARGET_KIND: "issue", + AUTHOR_ASSOCIATION: "MEMBER", + ACCESS_POLICY: "{", + REPOSITORY_PRIVATE: "true", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 2); + assert.match(result.stderr, /Invalid AGENT_ACCESS_POLICY:/); + assert.doesNotMatch(result.stderr, /at parseAccessPolicy/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-dispatch uses generated metadata for explicit implement tracking issues", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-dispatch-")); + + try { + const outputPath = join(tempDir, "github-output.txt"); + const metadataPath = join(tempDir, "metadata.json"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + metadataPath, + JSON.stringify({ + issue_title: "Fix explicit implement issue titles", + issue_body: "## Goal\nGenerate titles from PR context.\n\n## Acceptance criteria\n- Ignore earlier prose command mentions.", + base_pr: "268", + }), + "utf8", + ); + + const result = spawnSync("node", [".agent/dist/cli/resolve-dispatch.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + RESPONSE_FILE: metadataPath, + REQUESTED_ROUTE: "implement", + REQUEST_TEXT: "Earlier prose mentions /implement with stale wording.\n\n@sepo-agent /implement", + TARGET_KIND: "pull_request", + AUTHOR_ASSOCIATION: "MEMBER", + ACCESS_POLICY: "", + REPOSITORY_PRIVATE: "true", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("route"), "implement"); + assert.equal(outputs.get("needs_approval"), "false"); + assert.equal(outputs.get("issue_title"), "Fix explicit implement issue titles"); + assert.doesNotMatch(outputs.get("issue_title") || "", /stale wording/); + assert.match(outputs.get("issue_body") || "", /Generate titles from PR context/); + assert.equal(outputs.get("base_pr"), "268"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-dispatch falls back when generated implement metadata is invalid", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-dispatch-")); + + try { + const outputPath = join(tempDir, "github-output.txt"); + const metadataPath = join(tempDir, "metadata.json"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync(metadataPath, '{"issue_title":"Missing body"}', "utf8"); + + const result = spawnSync("node", [".agent/dist/cli/resolve-dispatch.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + RESPONSE_FILE: metadataPath, + REQUESTED_ROUTE: "implement", + REQUEST_TEXT: "@sepo-agent /implement", + TARGET_KIND: "pull_request", + AUTHOR_ASSOCIATION: "MEMBER", + ACCESS_POLICY: "", + REPOSITORY_PRIVATE: "true", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stderr, /using fallback metadata/); + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("issue_title"), "Implement requested change"); + assert.match(outputs.get("issue_body") || "", /Original request/); + assert.equal(outputs.get("base_pr"), ""); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-dispatch rejects invalid implement base PR metadata", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-resolve-dispatch-")); + + try { + const outputPath = join(tempDir, "github-output.txt"); + const metadataPath = join(tempDir, "metadata.json"); + writeFileSync(outputPath, "", "utf8"); + writeFileSync( + metadataPath, + JSON.stringify({ + issue_title: "Stack follow-up work", + issue_body: "## Goal\nCreate a stacked follow-up PR.", + base_pr: "#268", + }), + "utf8", + ); + + const result = spawnSync("node", [".agent/dist/cli/resolve-dispatch.js"], { + cwd: repoRoot, + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + RESPONSE_FILE: metadataPath, + REQUESTED_ROUTE: "implement", + REQUEST_TEXT: "@sepo-agent /implement work on this as a stacked PR?", + TARGET_KIND: "pull_request", + AUTHOR_ASSOCIATION: "MEMBER", + ACCESS_POLICY: "", + REPOSITORY_PRIVATE: "true", + }, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stderr, /base_pr must be a positive integer/); + const outputs = parseGithubOutput(outputPath); + assert.equal(outputs.get("base_pr"), ""); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/resolve-self-approve-cli.test.ts b/.agent/src/__tests__/resolve-self-approve-cli.test.ts new file mode 100644 index 0000000..820c628 --- /dev/null +++ b/.agent/src/__tests__/resolve-self-approve-cli.test.ts @@ -0,0 +1,240 @@ +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(raw: string): Map { + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + return outputs; +} + +function writeFakeGh( + tempDir: string, + headOid: string, + opts: { + failApprovalSubmission?: boolean; + failPrView?: boolean; + prAuthorLogin?: string; + synthesisAuthorLogin?: string; + viewerLogin?: string; + } = {}, +): string { + const prAuthorLogin = opts.prAuthorLogin || "lolipopshock"; + const viewerLogin = opts.viewerLogin || "sepo-agent-app"; + const synthesisAuthorLogin = opts.synthesisAuthorLogin || "sepo-agent-app"; + const logPath = join(tempDir, "gh.log"); + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + if [ "${opts.failPrView ? "true" : "false"}" = "true" ]; then + printf 'pr metadata unavailable\\n' >&2 + exit 1 + fi + printf '{"author":{"login":"${prAuthorLogin}"},"headRefName":"agent/test","headRefOid":"${headOid}","isCrossRepository":false,"state":"OPEN"}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":123,"body":"## AI Review Synthesis ## Final Verdict SHIP","created_at":"2026-05-07T10:00:00Z","user":{"login":"${synthesisAuthorLogin}"}}]]\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"${viewerLogin}"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--method" ] && [ "$3" = "POST" ]; then + if [ "${opts.failApprovalSubmission ? "true" : "false"}" = "true" ]; then + printf 'review API unavailable\\n' >&2 + exit 1 + fi + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); + return logPath; +} + +function runResolveSelfApprove(tempDir: string, responseBody: string): { + status: number | null; + stdout: string; + stderr: string; + output: string; + log: string; +} { + const responseFile = join(tempDir, "response.md"); + const outputFile = join(tempDir, "github-output"); + writeFileSync(responseFile, responseBody, "utf8"); + writeFileSync(outputFile, "", "utf8"); + + const result = spawnSync("node", [".agent/dist/cli/resolve-self-approve.js"], { + cwd: repoRoot, + env: { + ...process.env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_APPROVE: "true", + EXPECTED_HEAD_SHA: "abc123", + FAKE_GH_LOG: join(tempDir, "gh.log"), + GITHUB_OUTPUT: outputFile, + GITHUB_REPOSITORY: "self-evolving/repo", + RESPONSE_FILE: responseFile, + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, + encoding: "utf8", + }); + + return { + status: result.status, + stdout: result.stdout, + stderr: result.stderr, + output: readFileSync(outputFile, "utf8"), + log: readFileSync(join(tempDir, "gh.log"), "utf8"), + }; +} + +test("resolve-self-approve submits approval only for matching trusted head", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + mkdirSync(tempDir, { recursive: true }); + writeFakeGh(tempDir, "abc123"); + + const result = runResolveSelfApprove(tempDir, JSON.stringify({ + verdict: "APPROVE", + reason: "Aligned.", + inspected_head_sha: "abc123", + })); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /approved<<[^\n]+\ntrue/); + assert.match(result.output, /conclusion<<[^\n]+\napproved/); + assert.match(result.log, /^api --method POST repos\/self-evolving\/repo\/pulls\/42\/reviews /m); + assert.match(result.log, /commit_id=abc123/); + assert.match(result.log, /event=APPROVE/); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-approve blocks approval by the pull request author", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + writeFakeGh(tempDir, "abc123", { + prAuthorLogin: "app/sepo-agent-app", + viewerLogin: "sepo-agent-app[bot]", + }); + + const result = runResolveSelfApprove(tempDir, JSON.stringify({ + verdict: "APPROVE", + reason: "Aligned.", + inspected_head_sha: "abc123", + })); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /approved<<[^\n]+\nfalse/); + assert.match(result.output, /conclusion<<[^\n]+\nblocked/); + assert.match(result.output, /approval actor matches the pull request author/); + assert.doesNotMatch(result.log, /^api --method POST repos\/self-evolving\/repo\/pulls\/42\/reviews /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-approve does not submit approval after head changes", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + writeFakeGh(tempDir, "def456"); + + const result = runResolveSelfApprove(tempDir, JSON.stringify({ + verdict: "APPROVE", + reason: "Aligned.", + inspected_head_sha: "abc123", + })); + + assert.equal(result.status, 0, result.stderr); + assert.match(result.output, /approved<<[^\n]+\nfalse/); + assert.match(result.output, /conclusion<<[^\n]+\nblocked/); + assert.match(result.output, /pull request head changed/); + assert.doesNotMatch(result.log, /^api --method POST repos\/self-evolving\/repo\/pulls\/42\/reviews /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-approve writes failed status body when metadata cannot be read", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + writeFakeGh(tempDir, "abc123", { failPrView: true }); + + const result = runResolveSelfApprove(tempDir, JSON.stringify({ + verdict: "APPROVE", + reason: "Aligned.", + inspected_head_sha: "abc123", + })); + + assert.equal(result.status, 0, result.stderr); + const outputs = parseGithubOutput(result.output); + assert.equal(outputs.get("approved"), "false"); + assert.equal(outputs.get("conclusion"), "failed"); + assert.match(outputs.get("reason") || "", /could not read pull request metadata/); + const body = readFileSync(outputs.get("body_file") || "", "utf8"); + assert.match(body, /\| Failed \| `failed` \|/); + assert.match(body, /could not read pull request metadata/); + assert.match(body, //); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-approve writes failed status body for parser failures", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + writeFakeGh(tempDir, "abc123"); + + const result = runResolveSelfApprove(tempDir, "The agent did not return JSON."); + + assert.equal(result.status, 0, result.stderr); + const outputs = parseGithubOutput(result.output); + assert.equal(outputs.get("approved"), "false"); + assert.equal(outputs.get("conclusion"), "failed"); + assert.match(outputs.get("reason") || "", /missing a valid JSON decision/); + const body = readFileSync(outputs.get("body_file") || "", "utf8"); + assert.match(body, /\| Failed \| `failed` \|/); + assert.match(body, /missing a valid JSON decision/); + assert.doesNotMatch(result.log, /^api --method POST repos\/self-evolving\/repo\/pulls\/42\/reviews /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-approve writes failed status body when approval API fails", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-approve-cli-")); + try { + writeFakeGh(tempDir, "abc123", { failApprovalSubmission: true }); + + const result = runResolveSelfApprove(tempDir, JSON.stringify({ + verdict: "APPROVE", + reason: "Aligned.", + inspected_head_sha: "abc123", + })); + + assert.equal(result.status, 0, result.stderr); + const outputs = parseGithubOutput(result.output); + assert.equal(outputs.get("approved"), "false"); + assert.equal(outputs.get("conclusion"), "failed"); + assert.match(outputs.get("reason") || "", /approval submission failed/); + const body = readFileSync(outputs.get("body_file") || "", "utf8"); + assert.match(body, /\| Failed \| `failed` \|/); + assert.match(body, /approval submission failed/); + assert.match(result.log, /^api --method POST repos\/self-evolving\/repo\/pulls\/42\/reviews /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/resolve-self-merge-cli.test.ts b/.agent/src/__tests__/resolve-self-merge-cli.test.ts new file mode 100644 index 0000000..15624cf --- /dev/null +++ b/.agent/src/__tests__/resolve-self-merge-cli.test.ts @@ -0,0 +1,233 @@ +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +const repoRoot = resolve(__dirname, "../../.."); + +function parseGithubOutput(raw: string): Map { + const outputs = new Map(); + const blocks = raw.matchAll(/^([^<\n]+)<<([^\n]+)\n([\s\S]*?)\n\2$/gm); + for (const [, name, , value] of blocks) { + outputs.set(name, value); + } + return outputs; +} + +function writeFakeGh(tempDir: string): void { + writeFileSync(join(tempDir, "gh"), `#!/usr/bin/env bash +printf '%s\\n' "$*" >> "$FAKE_GH_LOG" +if [ "$1" = "pr" ] && [ "$2" = "view" ]; then + view_count_file="\${FAKE_GH_VIEW_COUNT_FILE-\${FAKE_GH_LOG}.view-count}" + view_count=0 + if [ -f "$view_count_file" ]; then + view_count="$(cat "$view_count_file")" + fi + printf '%s\\n' "$((view_count + 1))" > "$view_count_file" + auto_merge_request="\${FAKE_AUTO_MERGE_REQUEST-null}" + is_draft="\${FAKE_IS_DRAFT-false}" + merge_state="\${FAKE_MERGE_STATE-CLEAN}" + mergeable="\${FAKE_MERGEABLE-MERGEABLE}" + if [ "\${FAKE_READY_RECHECK-}" = "true" ] && [ "$view_count" -gt 0 ]; then + is_draft="\${FAKE_AFTER_READY_IS_DRAFT-false}" + merge_state="\${FAKE_AFTER_READY_MERGE_STATE-CLEAN}" + mergeable="\${FAKE_AFTER_READY_MERGEABLE-MERGEABLE}" + fi + printf '{"headRefOid":"abc123","isDraft":%s,"state":"%s","mergeStateStatus":"%s","mergeable":"%s","reviewDecision":"%s","statusCheckRollup":%s,"autoMergeRequest":%s}\\n' \ + "$is_draft" \ + "\${FAKE_PR_STATE-OPEN}" \ + "$merge_state" \ + "$mergeable" \ + "\${FAKE_REVIEW_DECISION-APPROVED}" \ + "\${FAKE_STATUS_CHECK_ROLLUP-[]}" \ + "$auto_merge_request" + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "graphql" ]; then + printf '{"data":{"viewer":{"login":"sepo-agent-app[bot]"}}}\\n' + exit 0 +fi +if [ "$1" = "api" ] && [ "$2" = "--paginate" ] && [ "$3" = "--slurp" ]; then + printf '[[{"id":123,"state":"APPROVED","body":"Sepo self-approval completed. ","commit_id":"%s","submitted_at":"2026-05-10T10:00:00Z","user":{"login":"sepo-agent-app"}}]]\\n' "\${FAKE_APPROVAL_HEAD-abc123}" + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "ready" ]; then + exit 0 +fi +if [ "$1" = "pr" ] && [ "$2" = "merge" ]; then + exit 0 +fi +printf 'unexpected gh args: %s\\n' "$*" >&2 +exit 1 +`, { encoding: "utf8", mode: 0o755 }); +} + +function runResolveSelfMerge(tempDir: string, env: Record = {}): { + status: number | null; + stderr: string; + outputs: Map; + log: string; +} { + const outputFile = join(tempDir, "github-output"); + writeFileSync(outputFile, "", "utf8"); + const result = spawnSync("node", [".agent/dist/cli/resolve-self-merge.js"], { + cwd: repoRoot, + env: { + ...process.env, + ...env, + PATH: `${tempDir}:${process.env.PATH || ""}`, + AGENT_ALLOW_SELF_MERGE: env.AGENT_ALLOW_SELF_MERGE || "true", + FAKE_GH_LOG: join(tempDir, "gh.log"), + GITHUB_OUTPUT: outputFile, + GITHUB_REPOSITORY: "self-evolving/repo", + TARGET_KIND: "pull_request", + TARGET_NUMBER: "42", + }, + encoding: "utf8", + }); + + return { + status: result.status, + stderr: result.stderr, + outputs: parseGithubOutput(readFileSync(outputFile, "utf8")), + log: readFileSync(join(tempDir, "gh.log"), "utf8"), + }; +} + +test("resolve-self-merge merges immediately when preflight passes", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "merged"); + assert.equal(result.outputs.get("merged"), "true"); + assert.equal(result.outputs.get("status_post"), "true"); + assert.match(readFileSync(result.outputs.get("body_file") || "", "utf8"), //); + assert.match(result.log, /^pr merge 42 --repo self-evolving\/repo --merge --match-head-commit abc123$/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge enables auto-merge when checks are pending", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir, { + FAKE_MERGE_STATE: "BLOCKED", + FAKE_MERGEABLE: "UNKNOWN", + FAKE_STATUS_CHECK_ROLLUP: '[{"name":"check","status":"IN_PROGRESS","conclusion":""}]', + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "auto_merge_enabled"); + assert.equal(result.outputs.get("auto_merge_enabled"), "true"); + assert.equal(result.outputs.get("status_post"), "true"); + assert.match(result.log, /^pr merge 42 --repo self-evolving\/repo --merge --auto --match-head-commit abc123$/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge blocks auto-merge when merge state is missing", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir, { + FAKE_MERGE_STATE: "", + FAKE_MERGEABLE: "UNKNOWN", + FAKE_STATUS_CHECK_ROLLUP: '[{"name":"check","status":"IN_PROGRESS","conclusion":""}]', + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "blocked"); + assert.match(result.outputs.get("reason") || "", /merge state: unknown/); + assert.doesNotMatch(result.log, /^pr merge /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge blocks existing auto-merge when merge state is ineligible", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir, { + FAKE_AUTO_MERGE_REQUEST: "{}", + FAKE_MERGE_STATE: "DIRTY", + FAKE_MERGEABLE: "MERGEABLE", + FAKE_STATUS_CHECK_ROLLUP: '[{"name":"check","status":"IN_PROGRESS","conclusion":""}]', + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "blocked"); + assert.equal(result.outputs.get("auto_merge_enabled"), "false"); + assert.match(result.outputs.get("reason") || "", /not eligible for auto-merge/); + assert.doesNotMatch(result.log, /^pr merge /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge marks draft PRs ready before merging", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir, { + FAKE_IS_DRAFT: "true", + FAKE_MERGE_STATE: "DRAFT", + FAKE_MERGEABLE: "UNKNOWN", + FAKE_READY_RECHECK: "true", + }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "merged"); + assert.equal((result.log.match(/^pr view /gm) || []).length, 2); + assert.match(result.log, /^pr ready 42 --repo self-evolving\/repo$/m); + assert.match(result.log, /^pr merge 42 --repo self-evolving\/repo --merge --match-head-commit abc123$/m); + assert.ok(result.log.indexOf("pr ready 42") < result.log.indexOf("pr merge 42")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge does not constrain the configured PR base", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "merged"); + assert.doesNotMatch(result.log, /^pr list /m); + assert.match(result.log, /^pr merge 42 --repo self-evolving\/repo --merge --match-head-commit abc123$/m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("resolve-self-merge blocks stale self-approval heads", () => { + const tempDir = mkdtempSync(join(tmpdir(), "agent-self-merge-cli-")); + try { + writeFakeGh(tempDir); + + const result = runResolveSelfMerge(tempDir, { FAKE_APPROVAL_HEAD: "old123" }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(result.outputs.get("conclusion"), "blocked"); + assert.match(result.outputs.get("reason") || "", /different head SHA/); + assert.doesNotMatch(result.log, /^pr merge /m); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/resolve-task-timeout-cli.test.ts b/.agent/src/__tests__/resolve-task-timeout-cli.test.ts new file mode 100644 index 0000000..4a111c0 --- /dev/null +++ b/.agent/src/__tests__/resolve-task-timeout-cli.test.ts @@ -0,0 +1,70 @@ +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + resolveTaskTimeoutMinutes, + runResolveTaskTimeoutCli, +} from "../cli/resolve-task-timeout.js"; + +test("resolveTaskTimeoutMinutes uses route overrides", () => { + assert.equal( + resolveTaskTimeoutMinutes({ + AGENT_TASK_TIMEOUT_POLICY: + '{"default_minutes": 30, "route_overrides": {"review": 45}}', + ROUTE: "review", + } as NodeJS.ProcessEnv), + 45, + ); +}); + +test("runResolveTaskTimeoutCli writes resolved minutes on success", () => { + const tempDir = mkdtempSync(join(tmpdir(), "resolve-task-timeout-")); + const outputFile = join(tempDir, "github-output"); + const originalOutput = process.env.GITHUB_OUTPUT; + const originalLog = console.log; + const logs: string[] = []; + process.env.GITHUB_OUTPUT = outputFile; + console.log = (message?: unknown) => { + logs.push(String(message || "")); + }; + try { + const code = runResolveTaskTimeoutCli({ + AGENT_TASK_TIMEOUT_POLICY: + '{"default_minutes": 30, "route_overrides": {"review": 45}}', + ROUTE: "review", + } as NodeJS.ProcessEnv); + assert.equal(code, 0); + assert.match(readFileSync(outputFile, "utf8"), /minutes<<.*\n45\n/s); + assert.match(logs.join("\n"), /task timeout: 45 minutes/); + } finally { + console.log = originalLog; + if (originalOutput === undefined) { + delete process.env.GITHUB_OUTPUT; + } else { + process.env.GITHUB_OUTPUT = originalOutput; + } + rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("runResolveTaskTimeoutCli fails clearly on malformed policy", () => { + const originalError = console.error; + const errors: string[] = []; + console.error = (message?: unknown) => { + errors.push(String(message || "")); + }; + try { + const code = runResolveTaskTimeoutCli({ + AGENT_TASK_TIMEOUT_POLICY: '{"default_minutes": "30"}', + ROUTE: "answer", + } as NodeJS.ProcessEnv); + assert.equal(code, 2); + assert.match(errors.join("\n"), /Invalid AGENT_TASK_TIMEOUT_POLICY/); + assert.match(errors.join("\n"), /default_minutes must be a positive integer/); + } finally { + console.error = originalError; + } +}); diff --git a/.agent/src/__tests__/response.test.ts b/.agent/src/__tests__/response.test.ts new file mode 100644 index 0000000..9b0f4c3 --- /dev/null +++ b/.agent/src/__tests__/response.test.ts @@ -0,0 +1,218 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + determineRunStatus, + extractJsonObject, + normalizeImplementationResponse, + summaryFromAgentResponse, + formatImplementComment, + formatFixPrComment, + formatReviewComment, + formatRubricsUpdateComment, +} from "../response.js"; + +// --- determineRunStatus --- + +test("determineRunStatus returns failed when agent exit is non-zero", () => { + assert.equal(determineRunStatus(1, true, 0), "failed"); +}); + +test("determineRunStatus returns no_changes when agent succeeded but no changes", () => { + assert.equal(determineRunStatus(0, false, 0), "no_changes"); +}); + +test("determineRunStatus returns success for clean branch head updates", () => { + assert.equal(determineRunStatus(0, false, 0, true), "success"); +}); + +test("determineRunStatus returns verify_failed for changed head when verify fails", () => { + assert.equal(determineRunStatus(0, false, 1, true), "verify_failed"); +}); + +test("determineRunStatus returns verify_failed when verify fails", () => { + assert.equal(determineRunStatus(0, true, 1), "verify_failed"); +}); + +test("determineRunStatus returns success when all checks pass", () => { + assert.equal(determineRunStatus(0, true, 0), "success"); +}); + +// --- extractJsonObject --- + +test("extractJsonObject extracts raw JSON", () => { + const json = extractJsonObject('{"summary":"done","pr_title":"feat: test"}'); + assert.equal(JSON.parse(json).summary, "done"); +}); + +test("extractJsonObject extracts fenced JSON", () => { + const json = extractJsonObject('```json\n{"summary":"done"}\n```'); + assert.equal(JSON.parse(json).summary, "done"); +}); + +test("extractJsonObject handles nested braces in strings", () => { + const json = extractJsonObject('{"body":"a { b } c"}'); + assert.equal(JSON.parse(json).body, "a { b } c"); +}); + +test("extractJsonObject returns empty for no JSON", () => { + assert.equal(extractJsonObject("just plain text"), ""); +}); + +// --- normalizeImplementationResponse --- + +test("normalizeImplementationResponse parses valid JSON", () => { + const result = normalizeImplementationResponse( + '{"summary":"Added feature","commit_message":"feat: add it","pr_title":"feat: add it","pr_body":"## Changes\\n- done"}' + ); + assert.equal(result.summary, "Added feature"); + assert.equal(result.commitMessage, "feat: add it"); + assert.equal(result.prTitle, "feat: add it"); + assert.match(result.prBody, /Changes/); +}); + +test("normalizeImplementationResponse falls back to plain text", () => { + const result = normalizeImplementationResponse("Just some plain text output"); + assert.equal(result.summary, "Just some plain text output"); + assert.equal(result.commitMessage, ""); + assert.equal(result.prTitle, ""); + assert.equal(result.prBody, ""); +}); + +test("normalizeImplementationResponse handles empty input", () => { + const result = normalizeImplementationResponse(""); + assert.equal(result.summary, ""); + assert.equal(result.commitMessage, ""); +}); + +test("normalizeImplementationResponse normalizes commit message whitespace", () => { + const result = normalizeImplementationResponse( + '{"summary":"Added feature","commit_message":"feat: add\\nfeature"}' + ); + assert.equal(result.commitMessage, "feat: add feature"); +}); + +test("summaryFromAgentResponse parses fix-pr JSON summaries", () => { + const summary = summaryFromAgentResponse( + "fix-pr", + '{"summary":"- Fixed the failing parser\\n- Added coverage","commit_message":"fix: repair parser"}' + ); + assert.equal(summary, "- Fixed the failing parser\n- Added coverage"); +}); + +test("summaryFromAgentResponse leaves review text unchanged", () => { + const summary = summaryFromAgentResponse("review", "## Summary\nLooks good."); + assert.equal(summary, "## Summary\nLooks good."); +}); + +// --- formatImplementComment --- + +test("formatImplementComment formats success with PR link", () => { + const body = formatImplementComment({ + status: "success", + summary: "Added the feature.", + branch: "agent/codex-42", + prUrl: "https://github.com/org/repo/pull/43", + }); + assert.match(body, /implementation finished/); + assert.match(body, /agent\/codex-42/); + assert.match(body, /pull\/43/); +}); + +test("formatImplementComment formats no_changes", () => { + const body = formatImplementComment({ status: "no_changes" }); + assert.match(body, /did not produce code changes/); +}); + +// --- formatFixPrComment --- + +test("formatFixPrComment formats success", () => { + const body = formatFixPrComment({ + status: "success", + branch: "feat/my-branch", + requestedBy: "alice", + }); + assert.match(body, /pushed fixes/); + assert.match(body, //); + assert.match(body, /@alice/); +}); + +test("formatFixPrComment accepts preformatted agent handles", () => { + const body = formatFixPrComment({ + status: "success", + branch: "feat/my-branch", + requestedBy: "@sepo-agent", + }); + assert.match(body, /Requested by @sepo-agent\./); + assert.doesNotMatch(body, /@@sepo-agent/); +}); + +test("formatFixPrComment formats unsupported", () => { + const body = formatFixPrComment({ status: "unsupported" }); + assert.match(body, /could not update this PR/); + assert.match(body, //); +}); + +// --- formatReviewComment --- + +test("formatReviewComment builds synthesis header", () => { + const body = formatReviewComment({ + synthesisBody: "## Summary\nLooks good.", + requestedBy: "bob", + reviewedHeadSha: "abc123", + }); + assert.match(body, /AI Review Synthesis/); + assert.match(body, //); + assert.match(body, //); + assert.match(body, /@bob/); + assert.match(body, /Looks good/); +}); + +// --- formatRubricsUpdateComment --- + +test("formatRubricsUpdateComment reports committed updates with summary", () => { + const body = formatRubricsUpdateComment({ + prNumber: 286, + rubricsRef: "agent/rubrics", + rubricsCommitted: true, + runSucceeded: true, + repoSlug: "self-evolving/repo", + summary: "Added docs sync rubric.", + }); + assert.match(body, /Rubrics Update/); + assert.match(body, /Updated \[`agent\/rubrics`\]\(https:\/\/github\.com\/self-evolving\/repo\/tree\/agent\/rubrics\) from PR #286/); + assert.match(body, /Added docs sync rubric/); +}); + +test("formatRubricsUpdateComment reports no changes", () => { + const body = formatRubricsUpdateComment({ + prNumber: "286", + rubricsRef: "agent/rubrics", + rubricsCommitted: false, + runSucceeded: true, + repoSlug: "self-evolving/repo", + summary: "no rubric changes", + }); + assert.match(body, /No changes were committed to \[`agent\/rubrics`\]\(https:\/\/github\.com\/self-evolving\/repo\/tree\/agent\/rubrics\) from PR #286/); + assert.match(body, /no rubric changes/); +}); + +test("formatRubricsUpdateComment falls back to code ref without repo slug", () => { + const body = formatRubricsUpdateComment({ + prNumber: "286", + rubricsRef: "agent/rubrics", + rubricsCommitted: false, + runSucceeded: true, + }); + assert.match(body, /No changes were committed to `agent\/rubrics` from PR #286/); +}); + +test("formatRubricsUpdateComment reports failed runs", () => { + const body = formatRubricsUpdateComment({ + prNumber: "286", + rubricsRef: "agent/rubrics", + rubricsCommitted: false, + runSucceeded: false, + }); + assert.match(body, /did not complete successfully/); +}); diff --git a/.agent/src/__tests__/review-summary-minimize.test.ts b/.agent/src/__tests__/review-summary-minimize.test.ts new file mode 100644 index 0000000..1bd7d12 --- /dev/null +++ b/.agent/src/__tests__/review-summary-minimize.test.ts @@ -0,0 +1,503 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + collapsePreviousFixPrComments, + collapsePreviousHandoffComments, + collapsePreviousReviewSummaries, + collapsePreviousRubricsReviews, + isRubricsReviewBody, +} from "../review-summary-minimize.js"; +import { isFixPrStatusBody } from "../fix-pr-status.js"; +import type { GraphQLClient, GraphQLVariableValue } from "../github-graphql.js"; + +function createQueuedClient(responses: unknown[]): { + client: GraphQLClient; + calls: Array<{ query: string; variables: Record }>; +} { + const calls: Array<{ query: string; variables: Record }> = []; + + const client: GraphQLClient = { + graphql( + query: string, + variables: Record, + ): T { + calls.push({ query, variables: { ...variables } }); + if (responses.length === 0) { + throw new Error("Unexpected GraphQL call"); + } + return responses.shift() as T; + }, + }; + + return { client, calls }; +} + +test("collapsePreviousReviewSummaries minimizes visible generated summaries", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "## AI Review Synthesis\n\n\nold", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-2", + body: "## AI Review Synthesis\nalready collapsed", + isMinimized: true, + author: { login: "sepo-agent" }, + }, + { + id: "comment-3", + body: "## AI Review Synthesis\nother author", + isMinimized: false, + author: { login: "alice" }, + }, + { + id: "comment-4", + body: "Regular discussion", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + reviews: { + nodes: [ + { + id: "review-1", + body: "\n## AI Review Synthesis\nold review", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + const collapsed = collapsePreviousReviewSummaries({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }); + + assert.equal(collapsed, 2); + assert.equal(calls.length, 5); + assert.match(calls[1]?.query || "", /comments/); + assert.deepEqual(calls[1]?.variables, { + owner: "self-evolving", + name: "repo", + number: 320, + after: undefined, + }); + assert.match(calls[2]?.query || "", /reviews/); + assert.deepEqual( + calls.slice(3).map((call) => call.variables), + [ + { id: "comment-1", classifier: "OUTDATED" }, + { id: "review-1", classifier: "OUTDATED" }, + ], + ); +}); + +test("collapsePreviousReviewSummaries matches GitHub App bot login variants", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent-app[bot]" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "## AI Review Synthesis\n\n\nold", + isMinimized: false, + author: { login: "app/sepo-agent-app" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + reviews: { + nodes: [], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + assert.equal(collapsePreviousReviewSummaries({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }), 1); + assert.deepEqual(calls[3]?.variables, { id: "comment-1", classifier: "OUTDATED" }); +}); + +test("collapsePreviousRubricsReviews minimizes rubrics reviews only", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "preface\n\n## Rubrics Review\nold rubric scorecard", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-2", + body: "## AI Review Synthesis\n\n\nold synthesis", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-3", + body: "## Rubrics Review\nother author", + isMinimized: false, + author: { login: "alice" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + reviews: { + nodes: [ + { + id: "review-1", + body: "## Rubrics Review\nold review body", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + const collapsed = collapsePreviousRubricsReviews({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }); + + assert.equal(collapsed, 2); + assert.deepEqual( + calls.slice(3).map((call) => call.variables), + [ + { id: "comment-1", classifier: "OUTDATED" }, + { id: "review-1", classifier: "OUTDATED" }, + ], + ); +}); + +test("collapsePreviousFixPrComments minimizes fix-pr status comments only", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "**Sepo pushed fixes for this PR.** Branch: `agent/fix`.\n\n", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-2", + body: "**Sepo did not produce code changes for this PR.**\n\nlegacy body", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-3", + body: "## AI Review Synthesis\nnot a fix-pr status", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "comment-4", + body: "**Sepo pushed fixes for this PR.** other author", + isMinimized: false, + author: { login: "alice" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + const collapsed = collapsePreviousFixPrComments({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }); + + assert.equal(collapsed, 2); + assert.match(calls[1]?.query || "", /comments/); + assert.doesNotMatch(calls[1]?.query || "", /reviews/); + assert.deepEqual( + calls.slice(2).map((call) => call.variables), + [ + { id: "comment-1", classifier: "OUTDATED" }, + { id: "comment-2", classifier: "OUTDATED" }, + ], + ); +}); + +test("isFixPrStatusBody matches marker and legacy fix-pr status text", () => { + assert.equal(isFixPrStatusBody("> Restored session\n\n"), true); + assert.equal(isFixPrStatusBody("**Sepo could not update this PR automatically.**"), true); + assert.equal(isFixPrStatusBody("**Sepo could not complete the PR fix run.**"), true); + assert.equal( + isFixPrStatusBody( + "**Sepo made changes, but lightweight verification failed.**\n\n" + + "Inspect the workflow logs before retrying the PR fix run.", + ), + true, + ); + assert.equal(isFixPrStatusBody("**Sepo made changes, but lightweight verification failed.**"), false); + assert.equal(isFixPrStatusBody("## AI Review Synthesis\nbody"), false); +}); + +test("collapsePreviousHandoffComments minimizes old issue handoff comments only", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent-app[bot]" } }, + { + repository: { + issue: { + comments: { + nodes: [ + { + id: "old-handoff", + body: "Sepo automation handoff dispatched\n\n", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + { + id: "current-handoff", + body: "Sepo automation handoff dispatched\n\n", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + { + id: "pending-handoff", + body: "Sepo automation handoff pending\n\n", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + { + id: "newer-handoff", + body: "Sepo automation handoff dispatched\n\n", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + { + id: "other-body", + body: "Regular discussion", + isMinimized: false, + author: { login: "sepo-agent-app" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + const collapsed = collapsePreviousHandoffComments({ + repo: "self-evolving/repo", + targetNumber: 59, + targetKind: "issue", + excludeCommentId: "current-handoff", + currentCreatedAtMs: 456, + client, + }); + + assert.equal(collapsed, 1); + assert.match(calls[1]?.query || "", /issue\(number: \$number\)/); + assert.deepEqual(calls[2]?.variables, { id: "old-handoff", classifier: "OUTDATED" }); +}); + +test("collapsePreviousHandoffComments uses pull request comments for PR targets", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "old-handoff", + body: "", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + { + id: "current-handoff", + body: "", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + assert.equal(collapsePreviousHandoffComments({ + repo: "self-evolving/repo", + targetNumber: 57, + targetKind: "pull_request", + excludeCommentId: "current-handoff", + currentCreatedAtMs: 456, + client, + }), 1); + assert.match(calls[1]?.query || "", /pullRequest\(number: \$number\)/); + assert.deepEqual(calls[2]?.variables, { id: "old-handoff", classifier: "OUTDATED" }); +}); + +test("rubrics body detection matches heading after a continuity note", () => { + assert.equal(isRubricsReviewBody("> Restored session\n\n## Rubrics Review\nbody"), true); + assert.equal(isRubricsReviewBody("## AI Review Synthesis\nbody"), false); +}); + +test("collapsePreviousReviewSummaries keeps heading fallback for markerless summaries", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "## AI Review Synthesis\nold markerless comment", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + reviews: { + nodes: [], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + assert.equal(collapsePreviousReviewSummaries({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }), 1); + assert.deepEqual(calls[3]?.variables, { id: "comment-1", classifier: "OUTDATED" }); +}); + +test("collapsePreviousReviewSummaries paginates comments", () => { + const { client, calls } = createQueuedClient([ + { viewer: { login: "sepo-agent" } }, + { + repository: { + pullRequest: { + comments: { + nodes: [], + pageInfo: { hasNextPage: true, endCursor: "cursor-1" }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + comments: { + nodes: [ + { + id: "comment-1", + body: "## AI Review Synthesis\nold", + isMinimized: false, + author: { login: "sepo-agent" }, + }, + ], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { + repository: { + pullRequest: { + reviews: { + nodes: [], + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }, + }, + }, + { minimizeComment: { minimizedComment: { isMinimized: true } } }, + ]); + + assert.equal(collapsePreviousReviewSummaries({ + repo: "self-evolving/repo", + prNumber: 320, + client, + }), 1); + assert.equal(calls[1]?.variables.after, undefined); + assert.equal(calls[2]?.variables.after, "cursor-1"); +}); diff --git a/.agent/src/__tests__/review-synthesis.test.ts b/.agent/src/__tests__/review-synthesis.test.ts new file mode 100644 index 0000000..191c9b2 --- /dev/null +++ b/.agent/src/__tests__/review-synthesis.test.ts @@ -0,0 +1,42 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + buildReviewSynthesisHeadMarker, + extractReviewSynthesisHeadSha, + isReviewSynthesisBody, +} from "../review-synthesis.js"; + +test("buildReviewSynthesisHeadMarker formats non-empty head SHAs", () => { + assert.equal( + buildReviewSynthesisHeadMarker(" abc123 "), + "", + ); +}); + +test("buildReviewSynthesisHeadMarker omits blank head SHAs", () => { + assert.equal(buildReviewSynthesisHeadMarker(" "), ""); +}); + +test("extractReviewSynthesisHeadSha parses synthesis head markers", () => { + const body = [ + "## AI Review Synthesis", + "", + "", + "", + ].join("\n"); + + assert.equal(extractReviewSynthesisHeadSha(body), "AbC123def456"); +}); + +test("extractReviewSynthesisHeadSha ignores missing or malformed markers", () => { + assert.equal(extractReviewSynthesisHeadSha("## AI Review Synthesis"), ""); + assert.equal( + extractReviewSynthesisHeadSha(""), + "", + ); +}); + +test("isReviewSynthesisBody keeps legacy heading fallback", () => { + assert.equal(isReviewSynthesisBody("## AI Review Synthesis\n\nlegacy body"), true); +}); diff --git a/.agent/src/__tests__/rubrics.test.ts b/.agent/src/__tests__/rubrics.test.ts new file mode 100644 index 0000000..c0b21c1 --- /dev/null +++ b/.agent/src/__tests__/rubrics.test.ts @@ -0,0 +1,366 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { + ensureRubricsStructure, + formatRubricsForPrompt, + loadRubrics, + selectRubrics, + tokenizeRubricQuery, +} from "../rubrics.js"; +import { runRubricsSelectCli } from "../cli/rubrics/select.js"; +import { + getRubricsModeForRoute, + isRubricsHardDisabledRoute, + parseRubricsPolicy, + RUBRICS_HARD_DISABLED_ROUTES, + rubricsModeAllowsRead, + rubricsModeAllowsWrite, +} from "../rubrics-policy.js"; +import { resolveRubricsMode } from "../cli/rubrics/resolve-policy.js"; + +function tempDir(): string { + return mkdtempSync(join(tmpdir(), "rubrics-test-")); +} + +function writeRubric(root: string, name: string, body: string): void { + const dir = join(root, "rubrics", "coding"); + ensureRubricsStructure(root, "self-evolving/repo"); + writeFileSync(join(dir, name), body, "utf8"); +} + +function withoutGithubOutput(fn: () => T): T { + const previous = process.env.GITHUB_OUTPUT; + delete process.env.GITHUB_OUTPUT; + try { + return fn(); + } finally { + if (previous === undefined) { + delete process.env.GITHUB_OUTPUT; + } else { + process.env.GITHUB_OUTPUT = previous; + } + } +} + +test("ensureRubricsStructure seeds the user/team rubric branch layout", () => { + const root = tempDir(); + const result = ensureRubricsStructure(root, "self-evolving/repo"); + assert.ok(result.createdFiles.some((file) => file.endsWith("README.md"))); + assert.ok(result.createdFiles.some((file) => file.endsWith("rubrics/coding/.gitkeep"))); +}); + +test("loadRubrics validates and normalizes rubric YAML", () => { + const root = tempDir(); + writeRubric(root, "add-regression-tests.yaml", ` +schema_version: 1 +id: add-regression-tests +title: Add regression tests +description: >- + Bug fixes should include regression tests. +type: generic +domain: coding_workflow +applies_to: + - implement +severity: must +weight: 5 +status: active +examples: + - source: https://example.test/pr/1 + note: Reviewer requested a regression test. +`); + + const { rubrics, errors } = loadRubrics(root); + assert.deepEqual(errors, []); + assert.equal(rubrics.length, 1); + assert.equal(rubrics[0]?.id, "add-regression-tests"); + assert.equal(rubrics[0]?.severity, "must"); + assert.equal(rubrics[0]?.path, "rubrics/coding/add-regression-tests.yaml"); +}); + +test("loadRubrics accepts legacy category coding as coding_workflow", () => { + const root = tempDir(); + writeRubric(root, "legacy.yaml", ` +id: legacy-category +title: Legacy category +description: Legacy category should still load. +category: coding +applies_to: [implement] +`); + + const { rubrics, errors } = loadRubrics(root); + assert.deepEqual(errors, []); + assert.equal(rubrics[0]?.domain, "coding_workflow"); +}); + +test("loadRubrics rejects duplicate ids", () => { + const root = tempDir(); + const body = ` +id: duplicate-rubric +title: Duplicate +description: Same id. +applies_to: [implement] +`; + writeRubric(root, "one.yaml", body); + writeRubric(root, "two.yaml", body); + + const { rubrics, errors } = loadRubrics(root); + assert.equal(rubrics.length, 1); + assert.equal(errors.length, 1); + assert.match(errors[0]?.message || "", /duplicate id/); +}); + +test("loadRubrics rejects unsupported schema versions and invalid weights", () => { + const root = tempDir(); + writeRubric(root, "schema.yaml", ` +schema_version: 2 +id: future-rubric +title: Future schema +description: Future schema should not silently load. +applies_to: [implement] +`); + writeRubric(root, "weight.yaml", ` +id: bad-weight +title: Bad weight +description: Weight should be an integer from 1 to 10. +applies_to: [implement] +weight: 12 +`); + + const { rubrics, errors } = loadRubrics(root); + assert.equal(rubrics.length, 0); + assert.equal(errors.length, 2); + assert.ok(errors.some((error) => /schema_version must be 1/.test(error.message))); + assert.ok(errors.some((error) => /weight must be an integer from 1 to 10/.test(error.message))); +}); + +test("selectRubrics filters by route and ranks by query matches", () => { + const root = tempDir(); + writeRubric(root, "regression.yaml", ` +id: add-regression-tests +title: Add regression tests +description: Include regression tests for bug fixes. +applies_to: [implement] +severity: must +weight: 5 +`); + writeRubric(root, "concise.yaml", ` +id: concise-summary +title: Keep summaries concise +description: PR comments should be concise. +domain: communication +applies_to: [answer] +severity: should +weight: 2 +`); + + const { selected, errors } = selectRubrics({ + rootDir: root, + route: "implement", + query: "fix bug regression test", + }); + assert.deepEqual(errors, []); + assert.equal(selected.length, 1); + assert.equal(selected[0]?.rubric.id, "add-regression-tests"); + assert.ok(selected[0]?.matchedTerms.includes("regression")); +}); + +test("selectRubrics applies implementation rubrics to fix-pr", () => { + const root = tempDir(); + writeRubric(root, "implementation.yaml", ` +id: implementation-guidance +title: Implementation guidance +description: PR fixes should reuse implementation guidance. +applies_to: [implement] +severity: should +`); + + const { selected, errors } = selectRubrics({ + rootDir: root, + route: "fix-pr", + query: "fix pull request", + }); + assert.deepEqual(errors, []); + assert.equal(selected[0]?.rubric.id, "implementation-guidance"); +}); + +test("selectRubrics can include all routes for rubric review", () => { + const root = tempDir(); + writeRubric(root, "implementation.yaml", ` +id: implementation-guidance +title: Implementation guidance +description: Implementation guidance should be available to rubric review. +applies_to: [implement] +severity: should +`); + writeRubric(root, "answer.yaml", ` +id: answer-guidance +title: Answer guidance +description: Answer guidance should also be available to rubric review. +domain: communication +applies_to: [answer] +severity: should +`); + + const routeFiltered = selectRubrics({ + rootDir: root, + route: "rubrics-review", + query: "", + }); + assert.equal(routeFiltered.selected.length, 0); + + const allRoutes = selectRubrics({ + rootDir: root, + route: "rubrics-review", + query: "", + allRoutes: true, + limit: Number.POSITIVE_INFINITY, + }); + assert.deepEqual( + allRoutes.selected.map((entry) => entry.rubric.id).sort(), + ["answer-guidance", "implementation-guidance"], + ); +}); + +test("selectRubrics can filter by domain", () => { + const root = tempDir(); + writeRubric(root, "answer-workflow.yaml", ` +id: answer-workflow +title: Answer workflow +description: Workflow guidance can apply to answers. +domain: coding_workflow +applies_to: [answer] +severity: must +`); + writeRubric(root, "answer-communication.yaml", ` +id: answer-communication +title: Answer communication +description: Answer runs should prefer communication rubrics. +domain: communication +applies_to: [answer] +severity: should +`); + + const { selected, errors } = selectRubrics({ + rootDir: root, + route: "answer", + query: "", + domains: ["communication"], + }); + assert.deepEqual(errors, []); + assert.deepEqual(selected.map((entry) => entry.rubric.id), ["answer-communication"]); +}); + +test("rubrics select CLI can render valid rubrics in best-effort mode", () => { + const root = tempDir(); + writeRubric(root, "valid.yaml", ` +id: valid-rubric +title: Valid rubric +description: Valid rubrics should still be selected. +applies_to: [implement] +`); + writeRubric(root, "invalid.yaml", ` +id: invalid-rubric +title: Invalid rubric +description: Invalid rubrics should warn without blocking best-effort reads. +applies_to: [implement] +weight: 99 +`); + const outputFile = join(root, "selected.md"); + + const exitCode = withoutGithubOutput(() => runRubricsSelectCli([ + "--dir", root, + "--route", "implement", + "--query", "valid", + "--best-effort", + "--output-file", outputFile, + ], { GITHUB_OUTPUT: "" })); + + assert.equal(exitCode, 0); + assert.match(readFileSync(outputFile, "utf8"), /valid-rubric/); +}); + +test("rubrics select CLI filters answer rubrics by requested domains", () => { + const root = tempDir(); + writeRubric(root, "workflow.yaml", ` +id: workflow-answer +title: Workflow answer +description: Workflow answer guidance. +domain: coding_workflow +applies_to: [answer] +`); + writeRubric(root, "communication.yaml", ` +id: communication-answer +title: Communication answer +description: Communication answer guidance. +domain: communication +applies_to: [answer] +`); + const outputFile = join(root, "selected-answer.md"); + + const exitCode = withoutGithubOutput(() => runRubricsSelectCli([ + "--dir", root, + "--route", "answer", + "--domains", "communication", + "--output-file", outputFile, + ], { GITHUB_OUTPUT: "" })); + + const rendered = readFileSync(outputFile, "utf8"); + assert.equal(exitCode, 0); + assert.match(rendered, /communication-answer/); + assert.doesNotMatch(rendered, /workflow-answer/); +}); + +test("formatRubricsForPrompt renders selected rubrics as markdown", () => { + const root = tempDir(); + writeRubric(root, "regression.yaml", ` +id: add-regression-tests +title: Add regression tests +description: Include regression tests for bug fixes. +applies_to: [implement] +severity: must +weight: 5 +`); + const { selected } = selectRubrics({ rootDir: root, route: "implement", query: "regression" }); + const markdown = formatRubricsForPrompt(selected); + assert.match(markdown, /### Add regression tests/); + assert.match(markdown, /`add-regression-tests`/); +}); + +test("tokenizeRubricQuery drops short non-numeric tokens", () => { + assert.deepEqual(tokenizeRubricQuery("a PR 51 regression"), ["51", "regression"]); +}); + +test("rubrics policy defaults to read-only and supports route overrides", () => { + const empty = parseRubricsPolicy(""); + assert.equal(getRubricsModeForRoute(empty, "implement"), "read-only"); + assert.equal(rubricsModeAllowsRead("read-only"), true); + assert.equal(rubricsModeAllowsWrite("read-only"), false); + + const policy = parseRubricsPolicy(JSON.stringify({ + default_mode: "disabled", + route_overrides: { "rubrics-update": "enabled" }, + })); + assert.equal(getRubricsModeForRoute(policy, "answer"), "disabled"); + assert.equal(getRubricsModeForRoute(policy, "rubrics-update"), "enabled"); + + const dispatchPolicy = parseRubricsPolicy(JSON.stringify({ + default_mode: "enabled", + route_overrides: { dispatch: "enabled" }, + })); + assert.deepEqual(RUBRICS_HARD_DISABLED_ROUTES, ["dispatch"]); + assert.equal(isRubricsHardDisabledRoute("DISPATCH"), true); + assert.equal(getRubricsModeForRoute(dispatchPolicy, "dispatch"), "disabled"); +}); + +test("rubrics mode hard-disables dispatch triage", () => { + assert.equal(resolveRubricsMode({ ROUTE: "dispatch" }), "disabled"); + assert.equal(resolveRubricsMode({ + ROUTE: "dispatch", + RUBRICS_MODE_OVERRIDE: "enabled", + AGENT_RUBRICS_POLICY: JSON.stringify({ default_mode: "enabled" }), + }), "disabled"); +}); diff --git a/.agent/src/__tests__/runtime-state.test.ts b/.agent/src/__tests__/runtime-state.test.ts new file mode 100644 index 0000000..01b76fa --- /dev/null +++ b/.agent/src/__tests__/runtime-state.test.ts @@ -0,0 +1,206 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + buildRunningThreadStateFields, + buildThreadStateFieldsFromEnsureOutcome, + buildCompletedThreadStateUpdates, + buildFailedThreadStateUpdates, + resumeSessionIdFromForkSource, + resumeSessionIdFromState, + shouldFailRunBecauseOfEnsureOutcome, + shouldFailRunBecauseOfThreadStateError, + shouldFailBecauseRequiredResumeIdentityMissing, + shouldUseContinuationPrompt, +} from "../runtime-state.js"; +import { createThreadState, updateThreadState } from "../thread-state.js"; + +test("resumeSessionIdFromState only returns ids for resume policies", () => { + const state = updateThreadState(createThreadState("repo:issue:1:answer:default"), { + acpxSessionId: "ses-123", + }); + + assert.equal(resumeSessionIdFromState("none", state), undefined); + assert.equal(resumeSessionIdFromState("track-only", state), undefined); + assert.equal(resumeSessionIdFromState("resume-best-effort", state), "ses-123"); + assert.equal(resumeSessionIdFromState("resume-required", state), "ses-123"); +}); + +test("resumeSessionIdFromForkSource seeds resume-capable threads without destination identity", () => { + const existingWithIdentity = updateThreadState(createThreadState("repo:issue:1:implement:default"), { + acpxSessionId: "ses-destination", + }); + const existingWithoutIdentity = createThreadState("repo:issue:1:implement:default"); + + assert.equal(resumeSessionIdFromForkSource("none", null, "ses-source"), undefined); + assert.equal(resumeSessionIdFromForkSource("track-only", null, "ses-source"), undefined); + assert.equal(resumeSessionIdFromForkSource("resume-best-effort", existingWithIdentity, "ses-source"), undefined); + assert.equal(resumeSessionIdFromForkSource("resume-best-effort", null, ""), undefined); + assert.equal(resumeSessionIdFromForkSource("resume-best-effort", null, "ses-source"), "ses-source"); + assert.equal( + resumeSessionIdFromForkSource("resume-best-effort", existingWithoutIdentity, "ses-source"), + "ses-source", + ); +}); + +test("shouldUseContinuationPrompt only allows destination session resumes", () => { + const existingWithIdentity = updateThreadState(createThreadState("repo:issue:1:answer:default"), { + acpxSessionId: "ses-destination", + }); + const existingWithoutIdentity = createThreadState("repo:issue:1:implement:default"); + + assert.equal(shouldUseContinuationPrompt(existingWithIdentity, "ses-destination"), true); + assert.equal(shouldUseContinuationPrompt(existingWithIdentity, "ses-source"), false); + assert.equal(shouldUseContinuationPrompt(existingWithoutIdentity, "ses-source"), false); + assert.equal(shouldUseContinuationPrompt(null, "ses-source"), false); +}); + +test("buildRunningThreadStateFields resets resume metadata for a new attempt", () => { + assert.deepEqual(buildRunningThreadStateFields(), { + resume_status: "not_attempted", + last_resume_error: "", + resumed_from_session_id: "", + }); +}); + +test("buildThreadStateFieldsFromEnsureOutcome maps resumed and fallback outcomes", () => { + assert.deepEqual( + buildThreadStateFieldsFromEnsureOutcome({ kind: "resumed", resumedFromSessionId: "ses-old" }), + { + resume_status: "resumed", + last_resume_error: "", + resumed_from_session_id: "ses-old", + }, + ); + + assert.deepEqual( + buildThreadStateFieldsFromEnsureOutcome({ + kind: "resume_fallback", + resumedFromSessionId: "ses-old", + error: "expired", + }), + { + resume_status: "fallback_fresh", + last_resume_error: "expired", + resumed_from_session_id: "ses-old", + }, + ); +}); + +test("buildThreadStateFieldsFromEnsureOutcome maps failed and non-resume outcomes", () => { + assert.deepEqual( + buildThreadStateFieldsFromEnsureOutcome({ + kind: "failed", + resumedFromSessionId: "ses-old", + error: "resume + fresh failed", + }), + { + resume_status: "failed", + last_resume_error: "resume + fresh failed", + resumed_from_session_id: "ses-old", + }, + ); + + assert.deepEqual( + buildThreadStateFieldsFromEnsureOutcome({ kind: "fresh" }), + buildRunningThreadStateFields(), + ); + assert.deepEqual( + buildThreadStateFieldsFromEnsureOutcome({ kind: "not_applicable" }), + buildRunningThreadStateFields(), + ); +}); + +test("buildCompletedThreadStateUpdates preserves identity absence and records fallback", () => { + assert.deepEqual( + buildCompletedThreadStateUpdates({ + outcome: { + kind: "resume_fallback", + resumedFromSessionId: "ses-old", + error: "expired", + }, + identity: null, + }), + { + resume_status: "fallback_fresh", + last_resume_error: "expired", + resumed_from_session_id: "ses-old", + }, + ); + + assert.deepEqual( + buildCompletedThreadStateUpdates({ + outcome: { kind: "resumed", resumedFromSessionId: "ses-old" }, + identity: { acpxRecordId: "rec-new", acpxSessionId: "ses-new" }, + }), + { + resume_status: "resumed", + last_resume_error: "", + resumed_from_session_id: "ses-old", + acpxRecordId: "rec-new", + acpxSessionId: "ses-new", + }, + ); +}); + +test("buildFailedThreadStateUpdates records resume failure details", () => { + assert.deepEqual( + buildFailedThreadStateUpdates({ + kind: "failed", + resumedFromSessionId: "ses-old", + error: "boom", + }), + { + resume_status: "failed", + last_resume_error: "boom", + resumed_from_session_id: "ses-old", + }, + ); +}); + +test("strict continuity fails on fallback or thread-state errors only for resume-required", () => { + assert.equal( + shouldFailRunBecauseOfEnsureOutcome("resume-best-effort", { + kind: "resume_fallback", + resumedFromSessionId: "ses-old", + error: "expired", + }), + false, + ); + assert.equal( + shouldFailRunBecauseOfEnsureOutcome("resume-required", { + kind: "resume_fallback", + resumedFromSessionId: "ses-old", + error: "expired", + }), + true, + ); + assert.equal( + shouldFailRunBecauseOfEnsureOutcome("resume-required", { kind: "resumed", resumedFromSessionId: "ses-old" }), + false, + ); + assert.equal( + shouldFailRunBecauseOfEnsureOutcome("resume-required", { kind: "fresh" }), + false, + ); + + const existing = updateThreadState(createThreadState("repo:pr:7:fix-pr:default"), { + acpxSessionId: "", + }); + assert.equal( + shouldFailBecauseRequiredResumeIdentityMissing("resume-required", existing, undefined), + true, + ); + assert.equal( + shouldFailBecauseRequiredResumeIdentityMissing("resume-best-effort", existing, undefined), + false, + ); + assert.equal( + shouldFailBecauseRequiredResumeIdentityMissing("resume-required", null, undefined), + false, + ); + + assert.equal(shouldFailRunBecauseOfThreadStateError("track-only"), false); + assert.equal(shouldFailRunBecauseOfThreadStateError("resume-best-effort"), false); + assert.equal(shouldFailRunBecauseOfThreadStateError("resume-required"), true); +}); diff --git a/.agent/src/__tests__/schedule-policy.test.ts b/.agent/src/__tests__/schedule-policy.test.ts new file mode 100644 index 0000000..cb19507 --- /dev/null +++ b/.agent/src/__tests__/schedule-policy.test.ts @@ -0,0 +1,77 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + DEFAULT_SCHEDULE_MODE, + DEFAULT_SCHEDULE_WORKFLOW_OVERRIDES, + getScheduleModeForWorkflow, + isScheduleMode, + parseSchedulePolicy, +} from "../schedule-policy.js"; + +test("parseSchedulePolicy falls back to skip_no_updates when unset", () => { + const policy = parseSchedulePolicy(""); + assert.equal(policy.defaultMode, DEFAULT_SCHEDULE_MODE); + assert.equal(DEFAULT_SCHEDULE_MODE, "skip_no_updates"); + assert.deepEqual(policy.workflowOverrides, DEFAULT_SCHEDULE_WORKFLOW_OVERRIDES); + assert.equal(policy.workflowOverrides["agent-daily-summary.yml"], "disabled"); + assert.equal(policy.workflowOverrides["agent-memory-sync.yml"], "always_run"); +}); + +test("parseSchedulePolicy accepts workflow overrides", () => { + const policy = parseSchedulePolicy( + '{"default_mode":"skip_no_updates","workflow_overrides":{"agent-memory-sync.yml":"always_run","agent-daily-summary.yml":"disabled"}}', + ); + assert.equal(policy.defaultMode, "skip_no_updates"); + assert.equal(policy.workflowOverrides["agent-memory-sync.yml"], "always_run"); + assert.equal(policy.workflowOverrides["agent-daily-summary.yml"], "disabled"); +}); + +test("parseSchedulePolicy keeps daily summary disabled for unrelated policies", () => { + const policy = parseSchedulePolicy( + '{"workflow_overrides":{"agent-update.yml":"always_run"}}', + ); + assert.equal(getScheduleModeForWorkflow(policy, "agent-daily-summary.yml"), "disabled"); + assert.equal(getScheduleModeForWorkflow(policy, "agent-update.yml"), "always_run"); + + const enabled = parseSchedulePolicy( + '{"workflow_overrides":{"agent-daily-summary.yml":"skip_no_updates"}}', + ); + assert.equal(getScheduleModeForWorkflow(enabled, "agent-daily-summary.yml"), "skip_no_updates"); +}); + +test("parseSchedulePolicy normalizes workflow keys", () => { + const policy = parseSchedulePolicy('{"workflow_overrides":{"AGENT-MEMORY-SCAN.YML":"disabled"}}'); + assert.equal(policy.workflowOverrides["agent-memory-scan.yml"], "disabled"); +}); + +test("parseSchedulePolicy rejects invalid modes and workflow keys", () => { + assert.throws( + () => parseSchedulePolicy('{"default_mode":"banana"}'), + /default_mode must be one of/, + ); + assert.throws( + () => parseSchedulePolicy('{"workflow_overrides":{"../bad.yml":"disabled"}}'), + /Invalid workflow override key/, + ); + assert.throws( + () => parseSchedulePolicy('{"workflow_overrides":["agent-memory-scan.yml"]}'), + /workflow_overrides must be an object/, + ); +}); + +test("getScheduleModeForWorkflow prefers workflow override over default", () => { + const policy = parseSchedulePolicy( + '{"default_mode":"skip_no_updates","workflow_overrides":{"agent-memory-sync.yml":"always_run"}}', + ); + assert.equal(getScheduleModeForWorkflow(policy, "agent-memory-sync.yml"), "always_run"); + assert.equal(getScheduleModeForWorkflow(policy, "agent-memory-scan.yml"), "skip_no_updates"); +}); + +test("isScheduleMode gates string inputs", () => { + assert.equal(isScheduleMode("always_run"), true); + assert.equal(isScheduleMode("skip_no_updates"), true); + assert.equal(isScheduleMode("disabled"), true); + assert.equal(isScheduleMode("enabled"), false); + assert.equal(isScheduleMode(undefined), false); +}); diff --git a/.agent/src/__tests__/scheduled-activity.test.ts b/.agent/src/__tests__/scheduled-activity.test.ts new file mode 100644 index 0000000..029cfb3 --- /dev/null +++ b/.agent/src/__tests__/scheduled-activity.test.ts @@ -0,0 +1,317 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { + resolveCursorActivity, + resolveScheduledActivityGate, +} from "../scheduled-activity.js"; + +function runGit(args: string[], cwd: string): void { + const result = spawnSync("git", args, { cwd, encoding: "utf8" }); + assert.equal(result.status, 0, result.stderr); +} + +function runShellGate(env: Record) { + const tempDir = mkdtempSync(join(tmpdir(), "scheduled-gate-test-")); + const outputFile = join(tempDir, "outputs.txt"); + const result = spawnSync("bash", ["scripts/resolve-scheduled-activity-gate.sh"], { + cwd: process.cwd(), + env: { + ...process.env, + GITHUB_OUTPUT: outputFile, + GITHUB_REPOSITORY: "", + GH_TOKEN: "", + INPUT_GITHUB_TOKEN: "", + REPO_SLUG: "", + RUNNER_TEMP: tempDir, + ...env, + }, + encoding: "utf8", + }); + const outputText = result.status === 0 ? readFileSync(outputFile, "utf8") : ""; + const payload = result.stdout.trim() ? JSON.parse(result.stdout) : null; + return { result, outputText, payload }; +} + +function createCursorWorkspace(dependencyValue: string, selfValue: string): string { + const source = mkdtempSync(join(tmpdir(), "scheduled-gate-source-")); + const bare = mkdtempSync(join(tmpdir(), "scheduled-gate-origin-")); + const workspace = mkdtempSync(join(tmpdir(), "scheduled-gate-workspace-")); + + runGit(["init", "--bare"], bare); + runGit(["init"], source); + runGit(["config", "user.email", "sepo-agent@example.invalid"], source); + runGit(["config", "user.name", "sepo-agent"], source); + runGit(["remote", "add", "origin", bare], source); + + writeFileSync(join(source, "state.json"), `${JSON.stringify({ last_activity_at: dependencyValue })}\n`); + runGit(["add", "state.json"], source); + runGit(["commit", "-m", "sync state"], source); + runGit(["push", "origin", "HEAD:refs/agent-memory-state/sync"], source); + + writeFileSync(join(source, "state.json"), `${JSON.stringify({ last_scan_at: selfValue })}\n`); + runGit(["add", "state.json"], source); + runGit(["commit", "-m", "scan state"], source); + runGit(["push", "origin", "HEAD:refs/agent-memory-state/scan"], source); + + runGit(["init"], workspace); + runGit(["remote", "add", "origin", bare], workspace); + return workspace; +} + +test("resolveScheduledActivityGate bypasses policy for manual runs", () => { + const result = resolveScheduledActivityGate({ + eventName: "workflow_dispatch", + schedulePolicy: '{"default_mode":"disabled"}', + workflow: "agent-memory-scan.yml", + }); + assert.equal(result.skip, false); + assert.equal(result.mode, "disabled"); + assert.equal(result.reason, "non-scheduled run"); +}); + +test("resolveScheduledActivityGate supports disabling only automatic update checks", () => { + const policy = '{"workflow_overrides":{"agent-update.yml":"disabled"}}'; + const scheduled = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: policy, + workflow: "agent-update.yml", + }); + assert.equal(scheduled.skip, true); + assert.equal(scheduled.mode, "disabled"); + assert.equal(scheduled.reason, "schedule policy disabled workflow"); + + const manual = resolveScheduledActivityGate({ + eventName: "workflow_dispatch", + schedulePolicy: policy, + workflow: "agent-update.yml", + }); + assert.equal(manual.skip, false); + assert.equal(manual.mode, "disabled"); + assert.equal(manual.reason, "non-scheduled run"); +}); + +test("resolveScheduledActivityGate applies disabled and always_run modes", () => { + const disabled = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: '{"default_mode":"disabled"}', + workflow: "agent-memory-scan.yml", + }); + assert.equal(disabled.skip, true); + + const alwaysRun = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: '{"default_mode":"skip_no_updates","workflow_overrides":{"agent-memory-sync.yml":"always_run"}}', + workflow: "agent-memory-sync.yml", + }); + assert.equal(alwaysRun.skip, false); + assert.equal(alwaysRun.mode, "always_run"); +}); + +test("resolveScheduledActivityGate uses activity count when provided", () => { + const schedulePolicy = '{"workflow_overrides":{"agent-daily-summary.yml":"skip_no_updates"}}'; + const skipped = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy, + workflow: "agent-daily-summary.yml", + activityCount: "0", + }); + assert.equal(skipped.skip, true); + assert.equal(skipped.reason, "activity count is zero"); + + const run = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy, + workflow: "agent-daily-summary.yml", + activityCount: "3", + }); + assert.equal(run.skip, false); + assert.equal(run.reason, "activity count is nonzero"); +}); + +test("resolveScheduledActivityGate disables scheduled daily summary by default", () => { + const scheduled = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: "", + workflow: "agent-daily-summary.yml", + }); + assert.equal(scheduled.skip, true); + assert.equal(scheduled.mode, "disabled"); + assert.equal(scheduled.reason, "schedule policy disabled workflow"); + + const manual = resolveScheduledActivityGate({ + eventName: "workflow_dispatch", + schedulePolicy: "", + workflow: "agent-daily-summary.yml", + }); + assert.equal(manual.skip, false); + assert.equal(manual.mode, "disabled"); + assert.equal(manual.reason, "non-scheduled run"); +}); + +test("resolveScheduledActivityGate disables scheduled daily summary for unrelated policy", () => { + const scheduled = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: '{"workflow_overrides":{"agent-update.yml":"always_run"}}', + workflow: "agent-daily-summary.yml", + }); + assert.equal(scheduled.skip, true); + assert.equal(scheduled.mode, "disabled"); + assert.equal(scheduled.reason, "schedule policy disabled workflow"); +}); + +test("resolveScheduledActivityGate runs when skip_no_updates lacks detector config", () => { + const result = resolveScheduledActivityGate({ + eventName: "schedule", + schedulePolicy: '{"default_mode":"skip_no_updates"}', + workflow: "agent-memory-sync.yml", + }); + assert.equal(result.skip, false); + assert.equal(result.reason, "missing activity cursor configuration"); +}); + +test("scheduled-activity-gate shell script resolves disabled before runtime build", () => { + const { result, outputText } = runShellGate({ + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: '{"default_mode":"disabled"}', + WORKFLOW_FILENAME: "agent-memory-scan.yml", + }); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /"skip": true/); + assert.match(outputText, /skip<<[\s\S]*true/); +}); + +test("scheduled-activity-gate shell script matches core gate modes", () => { + for (const [name, env, expected] of [ + [ + "always_run override", + { + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: + '{"default_mode":"skip_no_updates","workflow_overrides":{"agent-memory-sync.yml":"always_run"}}', + WORKFLOW_FILENAME: "agent-memory-sync.yml", + }, + { skip: false, mode: "always_run", reason: "schedule policy always_run" }, + ], + [ + "daily summary default disabled", + { + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: "", + WORKFLOW_FILENAME: "agent-daily-summary.yml", + }, + { skip: true, mode: "disabled", reason: "schedule policy disabled workflow" }, + ], + [ + "daily summary unrelated policy disabled", + { + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: '{"workflow_overrides":{"agent-update.yml":"always_run"}}', + WORKFLOW_FILENAME: "agent-daily-summary.yml", + }, + { skip: true, mode: "disabled", reason: "schedule policy disabled workflow" }, + ], + [ + "activity count skip", + { + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: '{"workflow_overrides":{"agent-daily-summary.yml":"skip_no_updates"}}', + WORKFLOW_FILENAME: "agent-daily-summary.yml", + ACTIVITY_COUNT: "0", + }, + { skip: true, mode: "skip_no_updates", reason: "activity count is zero" }, + ], + [ + "activity count run", + { + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: '{"workflow_overrides":{"agent-daily-summary.yml":"skip_no_updates"}}', + WORKFLOW_FILENAME: "agent-daily-summary.yml", + ACTIVITY_COUNT: "3", + }, + { skip: false, mode: "skip_no_updates", reason: "activity count is nonzero" }, + ], + ] as const) { + const { result, payload } = runShellGate(env); + assert.equal(result.status, 0, `${name}: ${result.stderr}`); + assert.deepEqual( + { skip: payload.skip, mode: payload.mode, reason: payload.reason }, + expected, + name, + ); + } +}); + +test("scheduled-activity-gate shell script rejects invalid policy", () => { + const { result } = runShellGate({ + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: '{"default_mode":"banana"}', + WORKFLOW_FILENAME: "agent-memory-scan.yml", + }); + assert.equal(result.status, 2); + assert.match(result.stderr, /default_mode must be one of/); +}); + +test("scheduled-activity-gate shell script compares cursor refs", () => { + const skippedWorkspace = createCursorWorkspace( + "2026-04-27T10:00:00Z", + "2026-04-27T10:00:00.123Z", + ); + const skipped = runShellGate({ + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: "", + WORKFLOW_FILENAME: "agent-memory-scan.yml", + DEPENDENCY_REF: "refs/agent-memory-state/sync", + DEPENDENCY_FIELD: "last_activity_at", + SELF_REF: "refs/agent-memory-state/scan", + SELF_FIELD: "last_scan_at", + GITHUB_WORKSPACE: skippedWorkspace, + }); + assert.equal(skipped.result.status, 0, skipped.result.stderr); + assert.equal(skipped.payload.skip, true); + assert.equal(skipped.payload.reason, "dependency cursor has not advanced"); + + const runWorkspace = createCursorWorkspace( + "2026-04-27T11:00:00Z", + "2026-04-27T10:00:00Z", + ); + const run = runShellGate({ + GITHUB_EVENT_NAME: "schedule", + AGENT_SCHEDULE_POLICY: "", + WORKFLOW_FILENAME: "agent-memory-scan.yml", + DEPENDENCY_REF: "refs/agent-memory-state/sync", + DEPENDENCY_FIELD: "last_activity_at", + SELF_REF: "refs/agent-memory-state/scan", + SELF_FIELD: "last_scan_at", + GITHUB_WORKSPACE: runWorkspace, + }); + assert.equal(run.result.status, 0, run.result.stderr); + assert.equal(run.payload.skip, false); + assert.equal(run.payload.reason, "dependency cursor advanced"); +}); + +test("resolveCursorActivity skips only when dependency cursor has not advanced", () => { + const skipped = resolveCursorActivity( + "skip_no_updates", + "2026-04-27T10:00:00Z", + "2026-04-27T10:00:00Z", + ); + assert.equal(skipped.skip, true); + assert.equal(skipped.reason, "dependency cursor has not advanced"); + + const run = resolveCursorActivity( + "skip_no_updates", + "2026-04-27T11:00:00Z", + "2026-04-27T10:00:00Z", + ); + assert.equal(run.skip, false); + assert.equal(run.reason, "dependency cursor advanced"); + + const missing = resolveCursorActivity("skip_no_updates", "", "2026-04-27T10:00:00Z"); + assert.equal(missing.skip, false); + assert.equal(missing.reason, "missing or invalid activity cursor"); +}); diff --git a/.agent/src/__tests__/self-approval.test.ts b/.agent/src/__tests__/self-approval.test.ts new file mode 100644 index 0000000..51dd061 --- /dev/null +++ b/.agent/src/__tests__/self-approval.test.ts @@ -0,0 +1,354 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + evaluateSelfApprovalActor, + evaluateSelfApprovalProvenance, + formatSelfApprovalBody, + parseSelfApprovalDecision, + resolveSelfApproval, +} from "../self-approval.js"; + +const approveDecision = { + verdict: "approve" as const, + reason: "Aligned.", + handoffContext: "", + inspectedHeadSha: "abc123", +}; + +const distinctApprovalActor = { + approvalActorAllowed: true, + approvalActorReason: "approval actor is distinct from pull request author", +}; + +test("parseSelfApprovalDecision accepts structured verdict JSON", () => { + const decision = parseSelfApprovalDecision([ + "```json", + JSON.stringify({ + verdict: "REQUEST_CHANGES", + reason: "The product direction needs a narrower trust boundary.", + handoff_context: "Keep self-approval internal-only.", + inspected_head_sha: "abc123", + }), + "```", + ].join("\n")); + + assert.equal(decision?.verdict, "request_changes"); + assert.equal(decision?.reason, "The product direction needs a narrower trust boundary."); + assert.equal(decision?.handoffContext, "Keep self-approval internal-only."); + assert.equal(decision?.inspectedHeadSha, "abc123"); +}); + +test("parseSelfApprovalDecision rejects malformed or unsupported decisions", () => { + assert.equal(parseSelfApprovalDecision("no json"), null); + assert.equal(parseSelfApprovalDecision('{"verdict":"MAYBE","reason":"unsure"}'), null); + assert.equal(parseSelfApprovalDecision("[1,2,3]"), null); +}); + +test("formatSelfApprovalBody surfaces blocked and failed conclusions visibly", () => { + const blocked = formatSelfApprovalBody({ + conclusion: "blocked", + reason: "missing trusted review synthesis", + }); + assert.match(blocked, /\| Blocked \| `blocked` \|/); + assert.match(blocked, //); + + const failed = formatSelfApprovalBody({ + conclusion: "failed", + reason: "approval submission failed: unavailable", + }); + assert.match(failed, /\| Failed \| `failed` \|/); + assert.match(failed, /approval submission failed/); +}); + +test("resolveSelfApproval blocks when opt-in flag is disabled", () => { + const result = resolveSelfApproval({ + allowSelfApprove: false, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: approveDecision, + approvalProvenanceTrusted: true, + }); + + assert.equal(result.shouldApprove, false); + assert.equal(result.conclusion, "blocked"); + assert.match(result.reason, /AGENT_ALLOW_SELF_APPROVE/); +}); + +test("resolveSelfApproval rejects non-PR and closed PR targets", () => { + const nonPr = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "issue", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: approveDecision, + approvalProvenanceTrusted: true, + }); + assert.equal(nonPr.shouldApprove, false); + assert.equal(nonPr.conclusion, "blocked"); + assert.match(nonPr.reason, /only supported for pull requests/); + + const closed = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "CLOSED", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: approveDecision, + approvalProvenanceTrusted: true, + }); + assert.equal(closed.shouldApprove, false); + assert.equal(closed.conclusion, "blocked"); + assert.match(closed.reason, /closed/); +}); + +test("evaluateSelfApprovalActor requires a distinct approval actor", () => { + const allowed = evaluateSelfApprovalActor({ + approvalActorLogin: "human-reviewer", + prAuthorLogin: "app/sepo-agent-app", + }); + assert.equal(allowed.allowed, true); + + const sameApp = evaluateSelfApprovalActor({ + approvalActorLogin: "sepo-agent-app[bot]", + prAuthorLogin: "app/sepo-agent-app", + }); + assert.equal(sameApp.allowed, false); + assert.match(sameApp.reason, /matches the pull request author/); + + const missing = evaluateSelfApprovalActor({ + approvalActorLogin: "", + prAuthorLogin: "lolipopshock", + }); + assert.equal(missing.allowed, false); + assert.match(missing.reason, /could not resolve approval actor/); +}); + +test("resolveSelfApproval approves only matching open PR heads with trusted provenance", () => { + const result = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: approveDecision, + ...distinctApprovalActor, + approvalProvenanceTrusted: true, + }); + + assert.equal(result.shouldApprove, true); + assert.equal(result.conclusion, "approved"); +}); + +test("resolveSelfApproval blocks approval by the pull request author", () => { + const result = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: approveDecision, + approvalActorAllowed: false, + approvalActorReason: "approval actor matches the pull request author", + approvalProvenanceTrusted: true, + }); + + assert.equal(result.shouldApprove, false); + assert.equal(result.conclusion, "blocked"); + assert.match(result.reason, /matches the pull request author/); +}); + +test("resolveSelfApproval rejects stale or mismatched head SHAs", () => { + const stale = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "def456", + decision: approveDecision, + approvalProvenanceTrusted: true, + }); + assert.equal(stale.shouldApprove, false); + assert.equal(stale.conclusion, "blocked"); + assert.match(stale.reason, /head changed/); + + const mismatch = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: { ...approveDecision, inspectedHeadSha: "def456" }, + approvalProvenanceTrusted: true, + }); + assert.equal(mismatch.shouldApprove, false); + assert.equal(mismatch.conclusion, "blocked"); + assert.match(mismatch.reason, /different inspected head/); +}); + +test("resolveSelfApproval rejects approval verdicts without inspected head SHA", () => { + for (const inspectedHeadSha of ["", " "]) { + const result = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + decision: { ...approveDecision, inspectedHeadSha }, + approvalProvenanceTrusted: true, + }); + + assert.equal(result.shouldApprove, false); + assert.equal(result.conclusion, "blocked"); + assert.match(result.reason, /missing inspected head SHA/); + } +}); + +test("resolveSelfApproval blocks approval without trusted review provenance", () => { + const result = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + ...distinctApprovalActor, + approvalProvenanceTrusted: false, + approvalProvenanceReason: "latest trusted review synthesis verdict is needs_rework, not SHIP", + decision: approveDecision, + }); + + assert.equal(result.shouldApprove, false); + assert.equal(result.conclusion, "blocked"); + assert.match(result.reason, /needs_rework/); +}); + +test("resolveSelfApproval records request changes without approving", () => { + const result = resolveSelfApproval({ + allowSelfApprove: true, + targetKind: "pull_request", + prState: "OPEN", + expectedHeadSha: "abc123", + currentHeadSha: "abc123", + approvalProvenanceTrusted: true, + decision: { + verdict: "request_changes", + reason: "Needs a narrower design.", + handoffContext: "Remove the public slash route.", + inspectedHeadSha: "abc123", + }, + }); + + assert.equal(result.shouldApprove, false); + assert.equal(result.conclusion, "request_changes"); + assert.equal(result.handoffContext, "Remove the public slash route."); +}); + +test("evaluateSelfApprovalProvenance requires the latest trusted ship signal", () => { + const trusted = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "abc123", + comments: [ + { + authorLogin: "app/sepo-agent-app", + createdAt: "2026-05-07T10:00:00Z", + body: "## AI Review Synthesis\n\n\n\n\n## Final Verdict\n\nSHIP", + }, + ], + }); + assert.equal(trusted.trusted, true); + assert.match(trusted.reason, /SHIP/); + + const superseded = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "abc123", + comments: [ + { + authorLogin: "sepo-agent-app", + createdAt: "2026-05-07T10:00:00Z", + body: "## AI Review Synthesis\n\n\n\n\n## Final Verdict\n\nSHIP", + }, + { + authorLogin: "sepo-agent-app", + createdAt: "2026-05-07T10:05:00Z", + body: "## AI Review Synthesis\n\n\n\n\n## Final Verdict\n\nNEEDS_REWORK", + }, + ], + }); + assert.equal(superseded.trusted, false); + assert.match(superseded.reason, /needs_rework/); +}); + +test("evaluateSelfApprovalProvenance can allow trusted HUMAN_DECISION gate", () => { + const humanDecision = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "abc123", + allowHumanDecisionGate: true, + comments: [ + { + authorLogin: "sepo-agent-app", + createdAt: "2026-05-07T10:00:00Z", + body: [ + "## AI Review Synthesis", + "", + "", + "", + "## Recommended Next Step", + "HUMAN_DECISION: self-approval should decide.", + "", + "## Final Verdict", + "NEEDS_REWORK", + ].join("\n"), + }, + ], + }); + assert.equal(humanDecision.trusted, true); + assert.match(humanDecision.reason, /HUMAN_DECISION/); + + const fixPr = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "abc123", + allowHumanDecisionGate: true, + comments: [ + { + authorLogin: "sepo-agent-app", + createdAt: "2026-05-07T10:00:00Z", + body: "## AI Review Synthesis\n\n\n\n## Recommended Next Step\nFIX_PR\n\n## Final Verdict\nNEEDS_REWORK", + }, + ], + }); + assert.equal(fixPr.trusted, false); + assert.match(fixPr.reason, /not SHIP/); +}); + +test("evaluateSelfApprovalProvenance requires review synthesis for the current head", () => { + const stale = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "def456", + comments: [ + { + authorLogin: "sepo-agent-app", + createdAt: "2026-05-07T10:00:00Z", + body: "## AI Review Synthesis\n\n\n\n\n## Final Verdict\n\nSHIP", + }, + ], + }); + assert.equal(stale.trusted, false); + assert.match(stale.reason, /different head SHA/); + + const untrusted = evaluateSelfApprovalProvenance({ + trustedActorLogin: "sepo-agent-app[bot]", + expectedHeadSha: "abc123", + comments: [ + { + authorLogin: "someone-else", + createdAt: "2026-05-07T10:00:00Z", + body: "## AI Review Synthesis\n\n\n\n\n## Final Verdict\n\nSHIP", + }, + ], + }); + assert.equal(untrusted.trusted, false); + assert.match(untrusted.reason, /missing trusted/); +}); diff --git a/.agent/src/__tests__/self-merge.test.ts b/.agent/src/__tests__/self-merge.test.ts new file mode 100644 index 0000000..4738332 --- /dev/null +++ b/.agent/src/__tests__/self-merge.test.ts @@ -0,0 +1,203 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + evaluateSelfMergeApproval, + formatSelfMergeBody, + resolveSelfMerge, + summarizeStatusChecks, +} from "../self-merge.js"; + +const approval = { + approved: true, + approvedHeadSha: "abc123", + reason: "found current-head self-approval from the authenticated Sepo actor", +}; + +const baseInput = { + allowSelfMerge: true, + targetKind: "pull_request", + prState: "OPEN", + isDraft: false, + currentHeadSha: "abc123", + reviewDecision: "APPROVED", + mergeStateStatus: "CLEAN", + mergeable: "MERGEABLE", + statusChecks: [], + approval, +}; + +test("evaluateSelfMergeApproval requires a current-head self-approval review", () => { + const current = evaluateSelfMergeApproval({ + trustedActorLogin: "sepo-agent-app[bot]", + currentHeadSha: "abc123", + reviews: [ + { + id: "1", + authorLogin: "app/sepo-agent-app", + state: "APPROVED", + commitId: "abc123", + submittedAt: "2026-05-10T10:00:00Z", + body: "Sepo self-approval completed.\n\n", + }, + ], + }); + assert.equal(current.approved, true); + + const stale = evaluateSelfMergeApproval({ + trustedActorLogin: "sepo-agent-app", + currentHeadSha: "def456", + reviews: [ + { + id: "1", + authorLogin: "sepo-agent-app[bot]", + state: "APPROVED", + commitId: "abc123", + submittedAt: "2026-05-10T10:00:00Z", + body: "Sepo self-approval completed.\n\n", + }, + ], + }); + assert.equal(stale.approved, false); + assert.match(stale.reason, /different head SHA/); + + const untrusted = evaluateSelfMergeApproval({ + trustedActorLogin: "sepo-agent-app", + currentHeadSha: "abc123", + reviews: [ + { + id: "1", + authorLogin: "someone-else", + state: "APPROVED", + commitId: "abc123", + submittedAt: "2026-05-10T10:00:00Z", + body: "Sepo self-approval completed.\n\n", + }, + ], + }); + assert.equal(untrusted.approved, false); + assert.match(untrusted.reason, /missing current-head self-approval/); +}); + +test("summarizeStatusChecks separates pending and failing checks", () => { + const summary = summarizeStatusChecks([ + { name: "build", status: "COMPLETED", conclusion: "SUCCESS", state: "" }, + { name: "test", status: "IN_PROGRESS", conclusion: "", state: "" }, + { name: "lint", status: "COMPLETED", conclusion: "FAILURE", state: "" }, + ]); + + assert.equal(summary.total, 3); + assert.deepEqual(summary.pendingNames, ["test"]); + assert.deepEqual(summary.failedNames, ["lint"]); +}); + +test("resolveSelfMerge blocks disabled, stale, requested-changes, and failed-check states", () => { + assert.match(resolveSelfMerge({ ...baseInput, allowSelfMerge: false }).reason, /AGENT_ALLOW_SELF_MERGE/); + assert.match( + resolveSelfMerge({ + ...baseInput, + approval: { approved: false, approvedHeadSha: "old", reason: "latest self-approval reviewed a different head SHA" }, + }).reason, + /different head SHA/, + ); + assert.match(resolveSelfMerge({ ...baseInput, reviewDecision: "CHANGES_REQUESTED" }).reason, /requested changes/); + assert.match( + resolveSelfMerge({ + ...baseInput, + statusChecks: [{ name: "test", status: "COMPLETED", conclusion: "FAILURE", state: "" }], + }).reason, + /status checks are failing: test/, + ); +}); + +test("resolveSelfMerge marks draft PRs ready before mergeability recheck", () => { + const readyToMerge = resolveSelfMerge({ + ...baseInput, + isDraft: true, + }); + assert.equal(readyToMerge.conclusion, "merged"); + assert.equal(readyToMerge.nextStep, "merge"); + assert.equal(readyToMerge.markReady, true); + + const needsRecheck = resolveSelfMerge({ + ...baseInput, + isDraft: true, + mergeStateStatus: "DRAFT", + mergeable: "UNKNOWN", + }); + assert.equal(needsRecheck.conclusion, "blocked"); + assert.equal(needsRecheck.nextStep, "none"); + assert.equal(needsRecheck.markReady, true); + assert.match(needsRecheck.reason, /not currently mergeable/); +}); + +test("resolveSelfMerge merges into the configured PR base when mergeable", () => { + const result = resolveSelfMerge(baseInput); + + assert.equal(result.conclusion, "merged"); + assert.equal(result.nextStep, "merge"); + + const blocked = resolveSelfMerge({ + ...baseInput, + mergeStateStatus: "BLOCKED", + mergeable: "UNKNOWN", + }); + assert.equal(blocked.conclusion, "blocked"); + assert.match(blocked.reason, /not currently mergeable/); +}); + +test("resolveSelfMerge enables auto-merge while checks are pending", () => { + const result = resolveSelfMerge({ + ...baseInput, + mergeStateStatus: "BLOCKED", + mergeable: "UNKNOWN", + statusChecks: [{ name: "check", status: "IN_PROGRESS", conclusion: "", state: "" }], + }); + + assert.equal(result.conclusion, "auto_merge_enabled"); + assert.equal(result.nextStep, "enable_auto_merge"); + assert.match(result.reason, /enabling GitHub auto-merge/); + + const alreadyEnabled = resolveSelfMerge({ + ...baseInput, + autoMergeRequestExists: true, + mergeStateStatus: "BLOCKED", + mergeable: "UNKNOWN", + statusChecks: [{ name: "check", status: "IN_PROGRESS", conclusion: "", state: "" }], + }); + assert.equal(alreadyEnabled.conclusion, "auto_merge_enabled"); + assert.equal(alreadyEnabled.nextStep, "none"); + + const ineligibleAlreadyEnabled = resolveSelfMerge({ + ...baseInput, + autoMergeRequestExists: true, + mergeStateStatus: "DIRTY", + mergeable: "MERGEABLE", + statusChecks: [{ name: "check", status: "IN_PROGRESS", conclusion: "", state: "" }], + }); + assert.equal(ineligibleAlreadyEnabled.conclusion, "blocked"); + assert.equal(ineligibleAlreadyEnabled.nextStep, "none"); + assert.match(ineligibleAlreadyEnabled.reason, /not eligible for auto-merge/); + + const missingMergeState = resolveSelfMerge({ + ...baseInput, + mergeStateStatus: "", + mergeable: "UNKNOWN", + statusChecks: [{ name: "check", status: "IN_PROGRESS", conclusion: "", state: "" }], + }); + assert.equal(missingMergeState.conclusion, "blocked"); + assert.equal(missingMergeState.nextStep, "none"); + assert.match(missingMergeState.reason, /merge state: unknown/); +}); + +test("formatSelfMergeBody includes visible status and marker", () => { + const body = formatSelfMergeBody({ + conclusion: "blocked", + reason: "pull request is not currently mergeable", + runUrl: "https://github.com/self-evolving/repo/actions/runs/123", + }); + + assert.match(body, /\| Blocked \| `blocked` \|/); + assert.match(body, /not currently mergeable/); + assert.match(body, //); +}); diff --git a/.agent/src/__tests__/session-bundle.test.ts b/.agent/src/__tests__/session-bundle.test.ts new file mode 100644 index 0000000..8047430 --- /dev/null +++ b/.agent/src/__tests__/session-bundle.test.ts @@ -0,0 +1,346 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + buildSessionBundleArtifactName, + createSessionBundle, + discoverSessionBundleFiles, + findSessionBundleArchive, + formatSessionRestoreNotice, + hasValidThreadTargetNumber, + isRestorableSessionBundleBackend, + parseSessionBundleMode, + restoreSessionBundle, + shouldBackupSessionBundles, + shouldRestoreSessionBundles, +} from "../session-bundle.js"; + +function makeTempDir(prefix: string): string { + return mkdtempSync(join(tmpdir(), prefix)); +} + +test("parseSessionBundleMode defaults to auto", () => { + assert.equal(parseSessionBundleMode(undefined), "auto"); + assert.equal(parseSessionBundleMode(""), "auto"); + assert.equal(parseSessionBundleMode("ALWAYS"), "always"); + assert.equal(parseSessionBundleMode("never"), "never"); +}); + +test("session bundle direction helpers separate restore from backup", () => { + assert.equal(shouldRestoreSessionBundles("auto", "none"), false); + assert.equal(shouldBackupSessionBundles("auto", "none"), false); + + assert.equal(shouldRestoreSessionBundles("auto", "track-only"), false); + assert.equal(shouldBackupSessionBundles("auto", "track-only"), false); + assert.equal(shouldRestoreSessionBundles("always", "track-only"), false); + assert.equal(shouldBackupSessionBundles("always", "track-only"), true); + assert.equal(shouldRestoreSessionBundles("never", "track-only"), false); + assert.equal(shouldBackupSessionBundles("never", "track-only"), false); + + assert.equal(shouldRestoreSessionBundles("auto", "resume-best-effort"), true); + assert.equal(shouldBackupSessionBundles("auto", "resume-best-effort"), true); + assert.equal(shouldRestoreSessionBundles("always", "resume-required"), true); + assert.equal(shouldBackupSessionBundles("always", "resume-required"), true); + + assert.equal(shouldRestoreSessionBundles("never", "resume-required"), false); + assert.equal(shouldBackupSessionBundles("never", "resume-required"), false); +}); + +test("debug session bundle backend is non-restorable", () => { + assert.equal(isRestorableSessionBundleBackend(""), true); + assert.equal(isRestorableSessionBundleBackend("github-artifact"), true); + assert.equal(isRestorableSessionBundleBackend("github-artifact-debug"), false); +}); + +test("hasValidThreadTargetNumber permits repository target_number=0", () => { + assert.equal(hasValidThreadTargetNumber("repository", 0), true); + assert.equal(hasValidThreadTargetNumber("repository", 1), true); + assert.equal(hasValidThreadTargetNumber("issue", 0), false); + assert.equal(hasValidThreadTargetNumber("pull_request", 42), true); + assert.equal(hasValidThreadTargetNumber("discussion", Number.NaN), false); +}); + +test("session bundle CLIs tolerate repository target_number=0", () => { + const cases = [ + { + script: "session-restore.js", + env: { SESSION_POLICY: "none", SESSION_BUNDLE_MODE: "auto" }, + }, + { + script: "session-backup.js", + env: { + ACPX_AGENT: "codex", + SESSION_POLICY: "resume-best-effort", + SESSION_BUNDLE_MODE: "always", + }, + }, + // Register skips without artifact metadata; the helper unit test covers validation. + { + script: "session-register.js", + env: { + SESSION_POLICY: "resume-best-effort", + SESSION_BUNDLE_MODE: "always", + }, + }, + ]; + + for (const entry of cases) { + const tempDir = makeTempDir("session-bundle-cli-"); + try { + const result = spawnSync( + process.execPath, + [join(process.cwd(), "dist", "cli", entry.script)], + { + cwd: process.cwd(), + env: { + ...process.env, + ...entry.env, + GITHUB_OUTPUT: join(tempDir, "github-output"), + GITHUB_REPOSITORY: "self-evolving/repo", + ROUTE: "answer", + TARGET_KIND: "repository", + TARGET_NUMBER: "0", + }, + encoding: "utf8", + }, + ); + + assert.equal( + result.status, + 0, + `${entry.script} failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`, + ); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + } +}); + +test("buildSessionBundleArtifactName is deterministic and includes route identity", () => { + const name = buildSessionBundleArtifactName( + "self-evolving/repo:pull_request:99:fix-pr:default", + "12345", + ); + assert.match(name, /^session-bundle-pull_request-99-fix-pr-default-/); + assert.match(name, /-12345$/); + assert.equal( + name, + buildSessionBundleArtifactName( + "self-evolving/repo:pull_request:99:fix-pr:default", + "12345", + ), + ); +}); + +test("formatSessionRestoreNotice reports fallback and failure outcomes", () => { + assert.match( + formatSessionRestoreNotice({ resumeStatus: "fallback_fresh", runStatus: "success" }), + /continued with a fresh session/, + ); + assert.match( + formatSessionRestoreNotice({ resumeStatus: "failed", runStatus: "failed" }), + /could not be restored/, + ); + assert.equal( + formatSessionRestoreNotice({ resumeStatus: "resumed", runStatus: "success" }), + "", + ); +}); + +test("discoverSessionBundleFiles finds acpx and codex provider files under HOME", () => { + const home = makeTempDir("session-bundle-home-"); + try { + mkdirSync(join(home, ".acpx", "sessions"), { recursive: true }); + mkdirSync(join(home, ".codex", "sessions", "2026", "04", "08"), { recursive: true }); + + writeFileSync(join(home, ".acpx", "sessions", "rec-1.json"), "{}\n"); + writeFileSync(join(home, ".acpx", "sessions", "rec-1.stream.ndjson"), "{}\n"); + writeFileSync( + join(home, ".codex", "sessions", "2026", "04", "08", "rollout-ses-1.jsonl"), + "hello\n", + ); + + const files = discoverSessionBundleFiles({ + agent: "codex", + acpxRecordId: "rec-1", + acpxSessionId: "ses-1", + homeDir: home, + }); + + assert.deepEqual( + files.map((file) => file.relative_path), + [ + ".acpx/sessions/rec-1.json", + ".acpx/sessions/rec-1.stream.ndjson", + ".codex/sessions/2026/04/08/rollout-ses-1.jsonl", + ], + ); + } finally { + rmSync(home, { recursive: true, force: true }); + } +}); + +test("discoverSessionBundleFiles treats session ids as literal text inside find globs", () => { + const home = makeTempDir("session-bundle-home-literal-"); + try { + mkdirSync(join(home, ".claude", "projects", "repo"), { recursive: true }); + writeFileSync( + join(home, ".claude", "projects", "repo", "abc[1].jsonl"), + "literal\n", + ); + + const files = discoverSessionBundleFiles({ + agent: "claude", + acpxRecordId: "", + acpxSessionId: "abc[1]", + homeDir: home, + }); + + assert.deepEqual( + files.map((file) => file.relative_path), + [".claude/projects/repo/abc[1].jsonl"], + ); + } finally { + rmSync(home, { recursive: true, force: true }); + } +}); + +test("createSessionBundle and restoreSessionBundle round-trip files", () => { + const sourceHome = makeTempDir("session-bundle-source-"); + const restoreHome = makeTempDir("session-bundle-restore-"); + const runnerTemp = makeTempDir("session-bundle-temp-"); + + try { + mkdirSync(join(sourceHome, ".acpx", "sessions"), { recursive: true }); + mkdirSync(join(sourceHome, ".codex", "sessions", "2026", "04", "08"), { recursive: true }); + + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-2.json"), '{"ok":true}\n'); + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-2.stream.ndjson"), "stream\n"); + writeFileSync( + join(sourceHome, ".codex", "sessions", "2026", "04", "08", "rollout-ses-2.jsonl"), + "provider\n", + ); + + const bundle = createSessionBundle({ + agent: "codex", + threadKey: "self-evolving/repo:pull_request:99:fix-pr:default", + repoSlug: "self-evolving/repo", + cwd: "/repo", + acpxRecordId: "rec-2", + acpxSessionId: "ses-2", + homeDir: sourceHome, + runnerTemp, + }); + + assert.ok(bundle); + assert.equal(bundle?.fileCount, 3); + assert.ok(findSessionBundleArchive(runnerTemp)); + + const manifest = restoreSessionBundle(bundle!.bundlePath, restoreHome); + assert.equal(manifest.acpx_record_id, "rec-2"); + assert.equal(manifest.acpx_session_id, "ses-2"); + + assert.equal( + readFileSync(join(restoreHome, ".acpx", "sessions", "rec-2.json"), "utf8"), + '{"ok":true}\n', + ); + assert.equal( + readFileSync(join(restoreHome, ".codex", "sessions", "2026", "04", "08", "rollout-ses-2.jsonl"), "utf8"), + "provider\n", + ); + } finally { + rmSync(sourceHome, { recursive: true, force: true }); + rmSync(restoreHome, { recursive: true, force: true }); + rmSync(runnerTemp, { recursive: true, force: true }); + } +}); + +test("restoreSessionBundle rejects checksum mismatches", () => { + const sourceHome = makeTempDir("session-bundle-source-bad-hash-"); + const restoreHome = makeTempDir("session-bundle-restore-bad-hash-"); + const runnerTemp = makeTempDir("session-bundle-temp-bad-hash-"); + const extracted = makeTempDir("session-bundle-edit-bad-hash-"); + + try { + mkdirSync(join(sourceHome, ".acpx", "sessions"), { recursive: true }); + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-3.json"), '{"ok":true}\n'); + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-3.stream.ndjson"), "stream\n"); + + const bundle = createSessionBundle({ + agent: "codex", + threadKey: "self-evolving/repo:pull_request:100:fix-pr:default", + repoSlug: "self-evolving/repo", + cwd: "/repo", + acpxRecordId: "rec-3", + acpxSessionId: "ses-3", + homeDir: sourceHome, + runnerTemp, + }); + + assert.ok(bundle); + + const tamperedTgz = join(runnerTemp, "tampered.tgz"); + execFileSync("tar", ["-xzf", bundle!.bundlePath, "-C", extracted]); + writeFileSync(join(extracted, "files", ".acpx", "sessions", "rec-3.json"), '{"ok":false}\n'); + execFileSync("tar", ["-czf", tamperedTgz, "-C", extracted, "manifest.json", "files"]); + + assert.throws( + () => restoreSessionBundle(tamperedTgz, restoreHome), + /checksum mismatch/, + ); + } finally { + rmSync(sourceHome, { recursive: true, force: true }); + rmSync(restoreHome, { recursive: true, force: true }); + rmSync(runnerTemp, { recursive: true, force: true }); + rmSync(extracted, { recursive: true, force: true }); + } +}); + +test("restoreSessionBundle rejects paths that escape HOME", () => { + const sourceHome = makeTempDir("session-bundle-source-escape-"); + const restoreHome = makeTempDir("session-bundle-restore-escape-"); + const runnerTemp = makeTempDir("session-bundle-temp-escape-"); + const extracted = makeTempDir("session-bundle-edit-escape-"); + + try { + mkdirSync(join(sourceHome, ".acpx", "sessions"), { recursive: true }); + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-4.json"), '{"ok":true}\n'); + writeFileSync(join(sourceHome, ".acpx", "sessions", "rec-4.stream.ndjson"), "stream\n"); + + const bundle = createSessionBundle({ + agent: "codex", + threadKey: "self-evolving/repo:pull_request:101:fix-pr:default", + repoSlug: "self-evolving/repo", + cwd: "/repo", + acpxRecordId: "rec-4", + acpxSessionId: "ses-4", + homeDir: sourceHome, + runnerTemp, + }); + + assert.ok(bundle); + execFileSync("tar", ["-xzf", bundle!.bundlePath, "-C", extracted]); + const manifestPath = join(extracted, "manifest.json"); + const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { + files: Array<{ relative_path: string }>; + }; + manifest.files[0].relative_path = "../../escape.txt"; + writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n"); + const tamperedTgz = join(runnerTemp, "tampered-escape.tgz"); + execFileSync("tar", ["-czf", tamperedTgz, "-C", extracted, "manifest.json", "files"]); + + assert.throws( + () => restoreSessionBundle(tamperedTgz, restoreHome), + /Invalid bundle path|escapes HOME/, + ); + } finally { + rmSync(sourceHome, { recursive: true, force: true }); + rmSync(restoreHome, { recursive: true, force: true }); + rmSync(runnerTemp, { recursive: true, force: true }); + rmSync(extracted, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/__tests__/session-policy.test.ts b/.agent/src/__tests__/session-policy.test.ts new file mode 100644 index 0000000..9833490 --- /dev/null +++ b/.agent/src/__tests__/session-policy.test.ts @@ -0,0 +1,47 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + parseSessionPolicy, + sessionModeForPolicy, + tracksThreadState, + attemptsResume, + requiresResumeContinuity, +} from "../session-policy.js"; + +test("parseSessionPolicy accepts only explicit policy values", () => { + assert.equal(parseSessionPolicy("none"), "none"); + assert.equal(parseSessionPolicy("track-only"), "track-only"); + assert.equal(parseSessionPolicy("resume-best-effort"), "resume-best-effort"); + assert.equal(parseSessionPolicy("resume-required"), "resume-required"); +}); + +test("parseSessionPolicy rejects empty or invalid values", () => { + assert.equal(parseSessionPolicy(""), null); + assert.equal(parseSessionPolicy(undefined), null); + assert.equal(parseSessionPolicy("wat"), null); +}); + +test("sessionModeForPolicy uses persistent sessions only for resume policies", () => { + assert.equal(sessionModeForPolicy("none"), "exec"); + assert.equal(sessionModeForPolicy("track-only"), "exec"); + assert.equal(sessionModeForPolicy("resume-best-effort"), "persistent"); + assert.equal(sessionModeForPolicy("resume-required"), "persistent"); +}); + +test("policy predicates separate tracking, resume, and strict continuity", () => { + assert.equal(tracksThreadState("none"), false); + assert.equal(tracksThreadState("track-only"), true); + assert.equal(tracksThreadState("resume-best-effort"), true); + assert.equal(tracksThreadState("resume-required"), true); + + assert.equal(attemptsResume("none"), false); + assert.equal(attemptsResume("track-only"), false); + assert.equal(attemptsResume("resume-best-effort"), true); + assert.equal(attemptsResume("resume-required"), true); + + assert.equal(requiresResumeContinuity("none"), false); + assert.equal(requiresResumeContinuity("track-only"), false); + assert.equal(requiresResumeContinuity("resume-best-effort"), false); + assert.equal(requiresResumeContinuity("resume-required"), true); +}); diff --git a/.agent/src/__tests__/sub-orchestration.test.ts b/.agent/src/__tests__/sub-orchestration.test.ts new file mode 100644 index 0000000..f6a6528 --- /dev/null +++ b/.agent/src/__tests__/sub-orchestration.test.ts @@ -0,0 +1,145 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + extractClosingIssueNumber, + formatSubOrchestrationIssueBody, + formatSubOrchestratorChildLinkMarker, + formatSubOrchestratorMarker, + normalizeSubOrchestratorStage, + parseSubOrchestratorChildLinkMarker, + parseSubOrchestratorMarker, + resultStateFromTerminal, + updateSubOrchestratorMarkerParentRound, + updateSubOrchestratorMarkerState, +} from "../sub-orchestration.js"; + +test("sub-orchestrator markers format, parse, and update", () => { + const marker = formatSubOrchestratorMarker({ + parent: 76, + stage: "Stage One!", + parentRound: 2, + }); + + assert.equal(marker, ""); + assert.deepEqual(parseSubOrchestratorMarker(marker), { + parent: 76, + stage: "stage-one", + state: "running", + parentRound: 2, + }); + assert.equal(normalizeSubOrchestratorStage(" A / B "), "a-b"); + assert.match(updateSubOrchestratorMarkerState(marker, "done"), /state:done/); + assert.match(updateSubOrchestratorMarkerParentRound(marker, 4), /parent_round:4/); +}); + +test("sub-orchestrator child link markers format and parse", () => { + const marker = formatSubOrchestratorChildLinkMarker({ + parent: 76, + stage: "Stage One", + child: 77, + }); + + assert.equal(marker, ""); + assert.deepEqual(parseSubOrchestratorChildLinkMarker(marker), { + parent: 76, + stage: "stage-one", + child: 77, + }); + assert.equal(parseSubOrchestratorChildLinkMarker("no marker"), null); +}); + +test("sub-orchestration issue body records visible task and hidden marker", () => { + const body = formatSubOrchestrationIssueBody({ + parentIssue: 76, + stage: "Stage One", + taskInstructions: "Implement the first stage.", + basePr: "66", + parentRound: 2, + }); + + assert.match(body, /Parent issue: #76/); + assert.match(body, /Stage: Stage One/); + assert.match(body, /Implement the first stage/); + assert.match(body, /base_pr: #66/); + assert.deepEqual(parseSubOrchestratorMarker(body), { + parent: 76, + stage: "stage-one", + state: "running", + parentRound: 2, + }); +}); + +test("terminal helpers resolve closing issue references and result states", () => { + assert.equal(extractClosingIssueNumber("Implements #76"), 76); + assert.equal(extractClosingIssueNumber("Fixes self-evolving/repo#76", "self-evolving/repo"), 76); + assert.equal(extractClosingIssueNumber("Fixes other-org/other-repo#76", "self-evolving/repo"), null); + assert.equal(extractClosingIssueNumber("Fixes self-evolving/repo#76"), null); + assert.equal(extractClosingIssueNumber("No linked issue"), null); + assert.equal(resultStateFromTerminal({ sourceAction: "review", sourceConclusion: "SHIP", reason: "" }), "done"); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-approve", sourceConclusion: "approved", reason: "" }), + "done", + ); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-approve", sourceConclusion: "blocked", reason: "" }), + "blocked", + ); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-approve", sourceConclusion: "failed", reason: "" }), + "failed", + ); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-merge", sourceConclusion: "merged", reason: "" }), + "done", + ); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-merge", sourceConclusion: "auto_merge_enabled", reason: "" }), + "done", + ); + assert.equal( + resultStateFromTerminal({ sourceAction: "agent-self-merge", sourceConclusion: "blocked", reason: "" }), + "blocked", + ); + assert.equal( + resultStateFromTerminal({ + sourceAction: "review", + sourceConclusion: "failed", + reason: "orchestrate requests require implement access; implement currently requires MEMBER access.", + }), + "blocked", + ); + assert.equal( + resultStateFromTerminal({ + sourceAction: "review", + sourceConclusion: "failed", + reason: "invalid AGENT_ACCESS_POLICY: Access policy must be a JSON object", + }), + "failed", + ); + assert.equal( + resultStateFromTerminal({ + sourceAction: "implement", + sourceConclusion: "failed", + reason: "automation round budget exhausted", + }), + "blocked", + ); + assert.equal( + resultStateFromTerminal({ + sourceAction: "orchestrate", + sourceConclusion: "failed", + reason: "agent planner blocked: waiting for user input", + }), + "blocked", + ); + assert.equal( + resultStateFromTerminal({ + sourceAction: "implement", + sourceConclusion: "failed", + reason: "provider said blocked while parsing output", + }), + "failed", + ); + assert.equal(resultStateFromTerminal({ sourceAction: "implement", sourceConclusion: "failed", reason: "" }), "failed"); +}); diff --git a/.agent/src/__tests__/task-timeout-policy.test.ts b/.agent/src/__tests__/task-timeout-policy.test.ts new file mode 100644 index 0000000..b2af89f --- /dev/null +++ b/.agent/src/__tests__/task-timeout-policy.test.ts @@ -0,0 +1,83 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + DEFAULT_TASK_TIMEOUT_MINUTES, + MAX_TASK_TIMEOUT_MINUTES, + getTaskTimeoutMinutesForRoute, + parseTaskTimeoutPolicy, +} from "../task-timeout-policy.js"; + +test("parseTaskTimeoutPolicy falls back to default minutes when unset", () => { + const policy = parseTaskTimeoutPolicy(""); + assert.equal(policy.defaultMinutes, DEFAULT_TASK_TIMEOUT_MINUTES); + assert.deepEqual(policy.routeOverrides, {}); + assert.equal(DEFAULT_TASK_TIMEOUT_MINUTES, 30); + assert.equal(MAX_TASK_TIMEOUT_MINUTES, 360); +}); + +test("parseTaskTimeoutPolicy accepts default_minutes alone", () => { + const policy = parseTaskTimeoutPolicy('{"default_minutes": 45}'); + assert.equal(policy.defaultMinutes, 45); + assert.deepEqual(policy.routeOverrides, {}); +}); + +test("parseTaskTimeoutPolicy accepts route_overrides alone", () => { + const policy = parseTaskTimeoutPolicy( + '{"route_overrides": {"review": 45, "fix-pr": 60}}', + ); + assert.equal(policy.defaultMinutes, DEFAULT_TASK_TIMEOUT_MINUTES); + assert.equal(policy.routeOverrides.review, 45); + assert.equal(policy.routeOverrides["fix-pr"], 60); +}); + +test("parseTaskTimeoutPolicy normalizes route keys to lowercase", () => { + const policy = parseTaskTimeoutPolicy('{"route_overrides": {"REVIEW": 40}}'); + assert.equal(policy.routeOverrides.review, 40); + assert.equal(policy.routeOverrides.REVIEW, undefined); +}); + +test("parseTaskTimeoutPolicy rejects invalid minute values", () => { + assert.throws( + () => parseTaskTimeoutPolicy('{"default_minutes": 0}'), + /default_minutes must be a positive integer/, + ); + assert.throws( + () => parseTaskTimeoutPolicy('{"default_minutes": 1.5}'), + /default_minutes must be a positive integer/, + ); + assert.throws( + () => parseTaskTimeoutPolicy('{"route_overrides": {"answer": "30"}}'), + /route_overrides\.answer must be a positive integer/, + ); + assert.throws( + () => parseTaskTimeoutPolicy('{"default_minutes": 361}'), + /default_minutes must be at most 360/, + ); + assert.throws( + () => parseTaskTimeoutPolicy('{"route_overrides": {"answer": 1000}}'), + /route_overrides\.answer must be at most 360/, + ); +}); + +test("parseTaskTimeoutPolicy rejects non-object route_overrides", () => { + assert.throws( + () => parseTaskTimeoutPolicy('{"route_overrides": ["answer", "review"]}'), + /route_overrides must be an object/, + ); +}); + +test("parseTaskTimeoutPolicy rejects invalid route keys", () => { + assert.throws( + () => parseTaskTimeoutPolicy('{"route_overrides": {"!bad": 30}}'), + /Invalid route override key/, + ); +}); + +test("getTaskTimeoutMinutesForRoute prefers override over default", () => { + const policy = parseTaskTimeoutPolicy( + '{"default_minutes": 30, "route_overrides": {"implement": 75}}', + ); + assert.equal(getTaskTimeoutMinutesForRoute(policy, "implement"), 75); + assert.equal(getTaskTimeoutMinutesForRoute(policy, "review"), 30); +}); diff --git a/.agent/src/__tests__/thread-state.test.ts b/.agent/src/__tests__/thread-state.test.ts new file mode 100644 index 0000000..7ee1066 --- /dev/null +++ b/.agent/src/__tests__/thread-state.test.ts @@ -0,0 +1,533 @@ +import { test } from "node:test"; +import { strict as assert } from "node:assert"; +import { execFileSync } from "node:child_process"; +import { mkdtempSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + THREAD_STATE_SCHEMA_VERSION, + createThreadState, + updateThreadState, + normalizeThreadState, + threadKeyToRefName, + refPathForThreadKey, + fetchThreadState, + writeThreadState, + markThreadRunning, + markThreadCompleted, + markThreadFailed, + markThreadBundleRestore, + markThreadBundleStored, +} from "../thread-state.js"; + +// --------------------------------------------------------------------------- +// Pure data operation tests +// --------------------------------------------------------------------------- + +const TEST_KEY = "self-evolving/repo:issue:21:implement:default"; + +test("createThreadState produces a valid initial state", () => { + const state = createThreadState(TEST_KEY); + + assert.equal(state.schema_version, THREAD_STATE_SCHEMA_VERSION); + assert.equal(state.thread_key, TEST_KEY); + assert.equal(state.acpxRecordId, ""); + assert.equal(state.acpxSessionId, ""); + assert.equal(state.agentSessionId, ""); + assert.equal(state.branch, ""); + assert.equal(state.status, "pending"); + assert.equal(state.resume_status, "not_attempted"); + assert.equal(state.last_resume_error, ""); + assert.equal(state.resumed_from_session_id, ""); + assert.equal(state.session_bundle_backend, ""); + assert.equal(state.session_bundle_artifact_id, ""); + assert.equal(state.session_bundle_artifact_name, ""); + assert.equal(state.session_bundle_run_id, ""); + assert.equal(state.bundle_restore_status, "not_attempted"); + assert.equal(state.last_bundle_restore_error, ""); + assert.equal(state.forked_from_thread_key, ""); + assert.equal(state.forked_from_acpx_session_id, ""); + assert.equal(state.last_run_url, ""); + assert.equal(state.last_comment_url, ""); + assert.equal(state.attempt_count, 0); + assert.ok(state.created_at); + assert.ok(state.updated_at); +}); + +test("updateThreadState merges updates and bumps updated_at", () => { + const state = createThreadState(TEST_KEY); + const originalCreated = state.created_at; + + const updated = updateThreadState(state, { + status: "running", + acpxRecordId: "rec-789", + attempt_count: 1, + }); + + assert.equal(updated.thread_key, TEST_KEY); + assert.equal(updated.status, "running"); + assert.equal(updated.acpxRecordId, "rec-789"); + assert.equal(updated.attempt_count, 1); + assert.equal(updated.created_at, originalCreated); + assert.ok(updated.updated_at >= originalCreated); +}); + +test("updateThreadState preserves thread_key even if updates try to change it", () => { + const state = createThreadState(TEST_KEY); + const updated = updateThreadState(state, { thread_key: "tampered" }); + assert.equal(updated.thread_key, TEST_KEY); +}); + +test("updateThreadState preserves created_at even if updates try to change it", () => { + const state = createThreadState(TEST_KEY); + const original = state.created_at; + const updated = updateThreadState(state, { created_at: "2020-01-01T00:00:00Z" }); + assert.equal(updated.created_at, original); +}); + +test("normalizeThreadState upgrades legacy resume_failed state", () => { + const legacy = normalizeThreadState({ + thread_key: TEST_KEY, + status: "resume_failed", + acpxSessionId: "ses-old", + attempt_count: 2, + created_at: "2026-01-01T00:00:00Z", + updated_at: "2026-01-01T01:00:00Z", + }); + + assert.ok(legacy); + assert.equal(legacy.schema_version, THREAD_STATE_SCHEMA_VERSION); + assert.equal(legacy.status, "failed"); + assert.equal(legacy.resume_status, "failed"); + assert.equal(legacy.acpxSessionId, "ses-old"); + assert.equal(legacy.bundle_restore_status, "not_attempted"); + assert.equal(legacy.forked_from_thread_key, ""); + assert.equal(legacy.forked_from_acpx_session_id, ""); + assert.equal(legacy.attempt_count, 2); +}); + +// --------------------------------------------------------------------------- +// Ref naming tests +// --------------------------------------------------------------------------- + +test("threadKeyToRefName converts slashes and colons", () => { + assert.equal( + threadKeyToRefName("self-evolving/repo:issue:42:implement:default"), + "self-evolving%2Frepo--issue--42--implement--default", + ); +}); + +test("threadKeyToRefName handles special characters", () => { + assert.equal( + threadKeyToRefName("org/repo:pull_request:7:fix-pr:claude"), + "org%2Frepo--pull_request--7--fix-pr--claude", + ); +}); + +test("threadKeyToRefName is injective: distinct keys with similar slugs don't collide", () => { + const a = threadKeyToRefName("foo/bar-baz:issue:1:implement:default"); + const b = threadKeyToRefName("foo-bar/baz:issue:1:implement:default"); + assert.notEqual(a, b, "different repo slugs must produce different ref names"); +}); + +test("threadKeyToRefName round-trips percent in key", () => { + const a = threadKeyToRefName("org/%2F:issue:1:r:l"); + const b = threadKeyToRefName("org//::issue:1:r:l"); + assert.notEqual(a, b); +}); + +test("refPathForThreadKey produces full ref path", () => { + assert.equal( + refPathForThreadKey("self-evolving/repo:issue:42:implement:default"), + "refs/agent-state/self-evolving%2Frepo--issue--42--implement--default", + ); +}); + +// --------------------------------------------------------------------------- +// Git integration test helpers +// --------------------------------------------------------------------------- + +let remoteDir: string; +let workDir: string; + +function gitIn(dir: string, args: string[]): string { + return execFileSync("git", args, { + cwd: dir, + stdio: ["pipe", "pipe", "pipe"], + }).toString("utf8").trim(); +} + +function setupRepos(): void { + const base = mkdtempSync(join(tmpdir(), "agent-ts-test-")); + remoteDir = join(base, "remote.git"); + workDir = join(base, "work"); + + execFileSync("git", ["init", "--bare", remoteDir], { stdio: "pipe" }); + execFileSync("git", ["clone", remoteDir, workDir], { stdio: "pipe" }); + + // git commit-tree needs author/committer identity + gitIn(workDir, ["config", "user.name", "test"]); + gitIn(workDir, ["config", "user.email", "test@test.com"]); +} + +function teardownRepos(): void { + try { + rmSync(join(remoteDir, ".."), { recursive: true, force: true }); + } catch { /* ok */ } +} + +// --------------------------------------------------------------------------- +// Git integration tests +// --------------------------------------------------------------------------- + +const GIT_TEST_KEY = "self-evolving/repo:issue:42:implement:default"; + +test("fetchThreadState returns null for nonexistent ref", () => { + setupRepos(); + try { + const result = fetchThreadState("nonexistent:key:1:route:lane", workDir); + assert.equal(result, null); + } finally { + teardownRepos(); + } +}); + +test("writeThreadState + fetchThreadState round-trip", () => { + setupRepos(); + try { + const state = updateThreadState(createThreadState(GIT_TEST_KEY), { + status: "running", + attempt_count: 1, + acpxRecordId: "rec-abc", + acpxSessionId: "ses-def", + }); + + writeThreadState(GIT_TEST_KEY, state, workDir); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.thread_key, GIT_TEST_KEY); + assert.equal(fetched.status, "running"); + assert.equal(fetched.attempt_count, 1); + assert.equal(fetched.acpxRecordId, "rec-abc"); + assert.equal(fetched.acpxSessionId, "ses-def"); + } finally { + teardownRepos(); + } +}); + +test("writeThreadState creates commit history (parent chain)", () => { + setupRepos(); + try { + const state1 = updateThreadState(createThreadState(GIT_TEST_KEY), { + status: "running", + attempt_count: 1, + }); + writeThreadState(GIT_TEST_KEY, state1, workDir); + + const state2 = updateThreadState(state1, { + status: "completed", + attempt_count: 2, + }); + writeThreadState(GIT_TEST_KEY, state2, workDir); + + const ref = refPathForThreadKey(GIT_TEST_KEY); + const log = gitIn(workDir, ["log", "--oneline", ref]); + const lines = log.split("\n").filter(Boolean); + assert.equal(lines.length, 2); + assert.match(lines[0], /completed.*attempt 2/); + assert.match(lines[1], /running.*attempt 1/); + } finally { + teardownRepos(); + } +}); + +test("refs don't appear in normal branch listing", () => { + setupRepos(); + try { + const state = updateThreadState(createThreadState(GIT_TEST_KEY), { + status: "running", + attempt_count: 1, + }); + writeThreadState(GIT_TEST_KEY, state, workDir); + + const branches = gitIn(workDir, ["branch", "-a"]); + assert.ok(!branches.includes("agent-state")); + } finally { + teardownRepos(); + } +}); + +test("multiple thread keys produce independent refs", () => { + setupRepos(); + try { + const key1 = "org/repo:issue:1:implement:default"; + const key2 = "org/repo:issue:2:review:default"; + + const state1 = updateThreadState(createThreadState(key1), { + status: "running", + attempt_count: 1, + }); + const state2 = updateThreadState(createThreadState(key2), { + status: "completed", + attempt_count: 3, + }); + + writeThreadState(key1, state1, workDir); + writeThreadState(key2, state2, workDir); + + const fetched1 = fetchThreadState(key1, workDir); + const fetched2 = fetchThreadState(key2, workDir); + + assert.ok(fetched1); + assert.ok(fetched2); + assert.equal(fetched1.status, "running"); + assert.equal(fetched1.attempt_count, 1); + assert.equal(fetched2.status, "completed"); + assert.equal(fetched2.attempt_count, 3); + } finally { + teardownRepos(); + } +}); + +test("markThreadRunning creates fresh state when none exists", () => { + setupRepos(); + try { + const state = markThreadRunning(GIT_TEST_KEY, workDir, { + last_run_url: "https://github.com/org/repo/actions/runs/123", + }); + + assert.equal(state.status, "running"); + assert.equal(state.attempt_count, 1); + assert.equal(state.last_run_url, "https://github.com/org/repo/actions/runs/123"); + assert.equal(state.forked_from_thread_key, ""); + assert.equal(state.forked_from_acpx_session_id, ""); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.status, "running"); + } finally { + teardownRepos(); + } +}); + +test("markThreadRunning bumps attempt_count on existing state", () => { + setupRepos(); + try { + markThreadRunning(GIT_TEST_KEY, workDir, { + last_run_url: "run-1", + forked_from_thread_key: "repo:issue:1:answer:default", + forked_from_acpx_session_id: "ses-source", + bundle_restore_status: "restored_from_fork", + last_bundle_restore_error: "", + }); + const state = markThreadRunning(GIT_TEST_KEY, workDir, { last_run_url: "run-2" }); + + assert.equal(state.status, "running"); + assert.equal(state.attempt_count, 2); + assert.equal(state.last_run_url, "run-2"); + assert.equal(state.forked_from_thread_key, "repo:issue:1:answer:default"); + assert.equal(state.forked_from_acpx_session_id, "ses-source"); + assert.equal(state.bundle_restore_status, "restored_from_fork"); + } finally { + teardownRepos(); + } +}); + +test("markThreadCompleted sets status and identity", () => { + setupRepos(); + try { + const running = markThreadRunning(GIT_TEST_KEY, workDir, {}); + + const completed = markThreadCompleted(GIT_TEST_KEY, running, workDir, { + acpxRecordId: "rec-final", + acpxSessionId: "ses-final", + }); + + assert.equal(completed.status, "completed"); + assert.equal(completed.acpxRecordId, "rec-final"); + assert.equal(completed.acpxSessionId, "ses-final"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.status, "completed"); + assert.equal(fetched.acpxRecordId, "rec-final"); + } finally { + teardownRepos(); + } +}); + +test("markThreadCompleted always produces completed state", () => { + setupRepos(); + try { + const running = markThreadRunning(GIT_TEST_KEY, workDir, {}); + + const completed = markThreadCompleted(GIT_TEST_KEY, running, workDir, { + acpxRecordId: "rec-x", + }); + + assert.equal(completed.status, "completed"); + assert.equal(completed.acpxRecordId, "rec-x"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.status, "completed"); + } finally { + teardownRepos(); + } +}); + +test("markThreadFailed records failed run status", () => { + setupRepos(); + try { + const running = markThreadRunning(GIT_TEST_KEY, workDir, {}); + + const failed = markThreadFailed(GIT_TEST_KEY, running, workDir, { + resume_status: "not_attempted", + }); + assert.equal(failed.status, "failed"); + assert.equal(failed.resume_status, "not_attempted"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.status, "failed"); + assert.equal(fetched.resume_status, "not_attempted"); + } finally { + teardownRepos(); + } +}); + +test("markThreadFailed records resume failure separately from run failure", () => { + setupRepos(); + try { + const running = markThreadRunning(GIT_TEST_KEY, workDir, {}); + const failed = markThreadFailed(GIT_TEST_KEY, running, workDir, { + resume_status: "failed", + last_resume_error: "resume expired", + resumed_from_session_id: "ses-old", + }); + + assert.equal(failed.status, "failed"); + assert.equal(failed.resume_status, "failed"); + assert.equal(failed.last_resume_error, "resume expired"); + assert.equal(failed.resumed_from_session_id, "ses-old"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.status, "failed"); + assert.equal(fetched.resume_status, "failed"); + assert.equal(fetched.resumed_from_session_id, "ses-old"); + } finally { + teardownRepos(); + } +}); + +test("markThreadBundleRestore records restore outcomes independently", () => { + setupRepos(); + try { + markThreadRunning(GIT_TEST_KEY, workDir, {}); + + const updated = markThreadBundleRestore( + GIT_TEST_KEY, + workDir, + { bundle_restore_status: "failed", last_bundle_restore_error: "artifact expired" }, + ); + + assert.ok(updated); + assert.equal(updated.bundle_restore_status, "failed"); + assert.equal(updated.last_bundle_restore_error, "artifact expired"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.bundle_restore_status, "failed"); + assert.equal(fetched.last_bundle_restore_error, "artifact expired"); + } finally { + teardownRepos(); + } +}); + +test("markThreadBundleRestore does not create fresh state on a missing thread", () => { + setupRepos(); + try { + const updated = markThreadBundleRestore( + GIT_TEST_KEY, + workDir, + { bundle_restore_status: "not_available", last_bundle_restore_error: "" }, + ); + + assert.equal(updated, null); + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.equal(fetched, null); + } finally { + teardownRepos(); + } +}); + +test("markThreadBundleStored records artifact pointer metadata", () => { + setupRepos(); + try { + const updated = markThreadBundleStored( + GIT_TEST_KEY, + workDir, + { + session_bundle_backend: "github-artifact", + session_bundle_artifact_id: "123", + session_bundle_artifact_name: "session-bundle-pr-42", + session_bundle_run_id: "456", + }, + ); + + assert.equal(updated.session_bundle_backend, "github-artifact"); + assert.equal(updated.session_bundle_artifact_id, "123"); + assert.equal(updated.session_bundle_artifact_name, "session-bundle-pr-42"); + assert.equal(updated.session_bundle_run_id, "456"); + + const fetched = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(fetched); + assert.equal(fetched.session_bundle_artifact_id, "123"); + assert.equal(fetched.session_bundle_run_id, "456"); + } finally { + teardownRepos(); + } +}); + +test("full lifecycle: create → running → completed with identity", () => { + setupRepos(); + try { + // 1. First run starts + const running = markThreadRunning(GIT_TEST_KEY, workDir, { + last_run_url: "https://github.com/org/repo/actions/runs/100", + branch: "agent/codex-42", + }); + assert.equal(running.status, "running"); + assert.equal(running.attempt_count, 1); + + // 2. Run completes with session identity + const completed = markThreadCompleted(GIT_TEST_KEY, running, workDir, { + acpxRecordId: "rec-abc", + acpxSessionId: "ses-def", + }); + assert.equal(completed.status, "completed"); + assert.equal(completed.acpxRecordId, "rec-abc"); + + // 3. Second run starts — reads prior state for resume + const prior = fetchThreadState(GIT_TEST_KEY, workDir); + assert.ok(prior); + assert.equal(prior.acpxSessionId, "ses-def"); // available for resume + + const running2 = markThreadRunning(GIT_TEST_KEY, workDir, { + last_run_url: "https://github.com/org/repo/actions/runs/200", + }); + assert.equal(running2.attempt_count, 2); + assert.equal(running2.acpxSessionId, "ses-def"); // preserved from prior + + // 4. Verify audit trail + const ref = refPathForThreadKey(GIT_TEST_KEY); + const log = gitIn(workDir, ["log", "--oneline", ref]); + const lines = log.split("\n").filter(Boolean); + assert.equal(lines.length, 3); // running(1) → completed → running(2) + } finally { + teardownRepos(); + } +}); diff --git a/.agent/src/__tests__/triage.test.ts b/.agent/src/__tests__/triage.test.ts new file mode 100644 index 0000000..6f0a266 --- /dev/null +++ b/.agent/src/__tests__/triage.test.ts @@ -0,0 +1,481 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +import { + ROUTES, + normalizeDispatch, + applyDispatchPolicy, + extractRequestedRoute, + extractRequestedRouteDecision, + buildRequestedRouteDecision, + normalizeImplementIssueMetadata, + resolveRequestedLabel, +} from "../triage.js"; +import { + getAllowedAssociationsForRoute, + isAssociationAllowedForRoute, + parseAccessPolicy, +} from "../access-policy.js"; + +const repoRoot = resolve(__dirname, "../../.."); + +function readRepoFile(relativePath: string): string { + return readFileSync(resolve(repoRoot, relativePath), "utf8"); +} + +// --- normalizeDispatch --- + +test("dispatch prompt enumerates every supported dispatch route", () => { + const prompt = readRepoFile(".github/prompts/agent-dispatch.md"); + const supportedRoutes = [...ROUTES].sort(); + + const bulletRoutes = Array.from( + prompt.matchAll(/^- `([^`]+)`: /gm), + ([, route]) => route, + ).sort(); + assert.deepEqual(bulletRoutes, supportedRoutes); + + const unionMatch = prompt.match(/"route": "([^"]+)"/); + assert.ok(unionMatch, "dispatch prompt should document the route JSON union"); + const unionRoutes = unionMatch[1] + .split("|") + .map((route) => route.trim()) + .sort(); + assert.deepEqual(unionRoutes, supportedRoutes); + assert.match(prompt, /Use `orchestrate` when/); +}); + +test("normalizeDispatch reads raw JSON", () => { + const d = normalizeDispatch( + '{"route":"answer","needs_approval":false,"summary":"Will answer.","confidence":"high","issue_title":"","issue_body":""}', + ); + assert.equal(d.route, "answer"); + assert.equal(d.needsApproval, false); + assert.equal(d.summary, "Will answer."); +}); + +test("normalizeDispatch reads fenced JSON", () => { + const d = normalizeDispatch( + '```json\n{"route":"implement","needs_approval":true,"summary":"Will implement.","confidence":"high","issue_title":"feat: add X","issue_body":"body"}\n```', + ); + assert.equal(d.route, "implement"); + assert.equal(d.issueTitle, "feat: add X"); +}); + +test("normalizeDispatch lowercases mixed-case routes", () => { + const d = normalizeDispatch('{"route":"Review","summary":"rev"}'); + assert.equal(d.route, "review"); +}); + +test("normalizeDispatch rejects empty input", () => { + assert.throws(() => normalizeDispatch(""), /empty/i); +}); + +test("normalizeDispatch rejects malformed JSON", () => { + assert.throws(() => normalizeDispatch("not json"), /JSON object/i); +}); + +test("normalizeDispatch rejects unsupported routes", () => { + assert.throws( + () => normalizeDispatch('{"route":"deploy"}'), + /Unsupported dispatch route/, + ); +}); + +test("parseAccessPolicy accepts future route override keys and GitHub associations", () => { + const policy = parseAccessPolicy( + JSON.stringify({ + route_overrides: { + "future-route": ["MANNEQUIN"], + }, + }), + ); + + assert.deepEqual(getAllowedAssociationsForRoute(policy, "future-route", false), ["MANNEQUIN"]); + assert.equal(isAssociationAllowedForRoute(policy, "future-route", "mannequin", false), true); +}); + +test("parseAccessPolicy rejects malformed policy values", () => { + assert.throws(() => parseAccessPolicy("{"), SyntaxError); + assert.throws(() => parseAccessPolicy("[1,2,3]"), /JSON object/); + assert.throws( + () => parseAccessPolicy(JSON.stringify({ allowed_associations: [] })), + /at least one author association/, + ); + assert.throws( + () => parseAccessPolicy(JSON.stringify({ allowed_associations: ["SUPERUSER"] })), + /unsupported author associations/, + ); + assert.throws( + () => parseAccessPolicy(JSON.stringify({ route_overrides: [] })), + /route_overrides must be an object/, + ); + assert.throws( + () => parseAccessPolicy(JSON.stringify({ route_overrides: { "--invalid": ["OWNER"] } })), + /Invalid route override key/, + ); + assert.throws( + () => parseAccessPolicy(JSON.stringify({ route_overrides: { answer: [] } })), + /route_overrides\.answer must contain at least one author association/, + ); +}); + +test("extractRequestedRoute detects explicit slash routes after the agent mention", () => { + assert.equal( + extractRequestedRoute("@sepo-agent /review this PR again", "@sepo-agent"), + "review", + ); + assert.equal( + extractRequestedRoute("Please check this.\n\n@sepo-agent /fix-pr handle the latest comments", "@sepo-agent"), + "fix-pr", + ); + assert.equal( + extractRequestedRoute("@sepo-agent /orchestrate continue intelligently", "@sepo-agent"), + "orchestrate", + ); + assert.equal( + extractRequestedRoute("@sepo-agent /create-action monitor flaky tests", "@sepo-agent"), + "create-action", + ); +}); + +test("extractRequestedRouteDecision detects mention-based skill requests", () => { + assert.deepEqual( + extractRequestedRouteDecision( + "@sepo-agent /skill Release-Notes summarize the changelog", + "@sepo-agent", + ), + { route: "skill", skill: "release-notes" }, + ); +}); + +test("extractRequestedRoute ignores non-route slash commands and commands without the mention", () => { + assert.equal( + extractRequestedRoute("@sepo-agent /approve req-a1b2c3", "@sepo-agent"), + "", + ); + assert.equal( + extractRequestedRoute("/review this PR again", "@sepo-agent"), + "", + ); + assert.deepEqual( + extractRequestedRouteDecision("@sepo-agent /skill ../../oops", "@sepo-agent"), + { route: "", skill: "" }, + ); +}); + +test("buildRequestedRouteDecision builds deterministic implement metadata without approval gate", () => { + const d = buildRequestedRouteDecision( + "implement", + "@sepo-agent /implement add a regression test for approval routing", + ); + assert.equal(d.route, "implement"); + // Explicit /implement is self-approval; the approval gate only applies to + // triaged implement decisions. + assert.equal(d.needsApproval, false); + assert.equal(d.issueTitle, "Implement requested change"); + assert.match(d.issueBody, /Original request/); +}); + +test("buildRequestedRouteDecision falls back to generic implement title without generated metadata", () => { + const d = buildRequestedRouteDecision("implement", "@sepo-agent /implement"); + assert.equal(d.issueTitle, "Implement requested change"); +}); + +test("buildRequestedRouteDecision uses generated implement issue metadata", () => { + const d = buildRequestedRouteDecision( + "implement", + "Earlier prose mentions /implement add the wrong title.\n\n@sepo-agent /implement", + { + issueTitle: "Fix webhook dispatch retry handling", + issueBody: "## Goal\nFix webhook dispatch retry handling.\n\n## Acceptance criteria\n- Add regression coverage.", + basePr: "268", + }, + ); + assert.equal(d.issueTitle, "Fix webhook dispatch retry handling"); + assert.doesNotMatch(d.issueTitle, /wrong title/); + assert.match(d.issueBody, /webhook dispatch retry/); + assert.equal(d.basePr, "268"); +}); + +test("normalizeImplementIssueMetadata reads generated JSON metadata", () => { + const metadata = normalizeImplementIssueMetadata( + '```json\n{"issue_title":"Fix PR tracking issue titles","issue_body":"## Goal\\nGenerate title from context.","base_pr":"268"}\n```', + ); + assert.equal(metadata.issueTitle, "Fix PR tracking issue titles"); + assert.match(metadata.issueBody, /Generate title from context/); + assert.equal(metadata.basePr, "268"); +}); + +test("normalizeImplementIssueMetadata rejects malformed generated metadata", () => { + assert.throws( + () => normalizeImplementIssueMetadata('{"issue_title":"Missing body"}'), + /missing issue_body/, + ); + assert.throws( + () => normalizeImplementIssueMetadata('{"issue_title":"Bad base","issue_body":"body","base_pr":"#268"}'), + /base_pr must be a positive integer/, + ); + assert.throws( + () => normalizeImplementIssueMetadata('{"issue_title":"Bad base","issue_body":"body","base_pr":"0"}'), + /base_pr must be a positive integer/, + ); +}); + +test("buildRequestedRouteDecision builds deterministic review metadata", () => { + const d = buildRequestedRouteDecision("review", "@sepo-agent /review"); + assert.equal(d.route, "review"); + assert.equal(d.needsApproval, false); + assert.equal(d.issueTitle, ""); + assert.equal(d.issueBody, ""); +}); + +test("buildRequestedRouteDecision builds deterministic orchestrate metadata", () => { + const d = buildRequestedRouteDecision("orchestrate", "@sepo-agent /orchestrate"); + assert.equal(d.route, "orchestrate"); + assert.equal(d.needsApproval, false); + assert.equal(d.issueTitle, ""); + assert.equal(d.issueBody, ""); +}); + +test("buildRequestedRouteDecision builds deterministic create-action metadata", () => { + const d = buildRequestedRouteDecision( + "create-action", + "@sepo-agent /create-action monitor flaky tests", + ); + assert.equal(d.route, "create-action"); + assert.equal(d.needsApproval, false); + assert.equal(d.issueTitle, "Create scheduled agent workflow"); + assert.match(d.issueBody, /scheduled GitHub Actions workflow/); +}); + +test("buildRequestedRouteDecision supports skill routes", () => { + const d = buildRequestedRouteDecision("skill", "agent/s/release-notes"); + assert.equal(d.route, "skill"); + assert.equal(d.needsApproval, false); +}); + +test("resolveRequestedLabel maps built-in and skill labels", () => { + assert.deepEqual(resolveRequestedLabel("agent/review"), { route: "review", skill: "" }); + assert.deepEqual(resolveRequestedLabel("agent/orchestrate"), { route: "orchestrate", skill: "" }); + assert.deepEqual(resolveRequestedLabel("agent/create-action"), { + route: "create-action", + skill: "", + }); + assert.deepEqual(resolveRequestedLabel("agent/s/release-notes"), { + route: "skill", + skill: "release-notes", + }); +}); + +test("resolveRequestedLabel normalizes skill name to lowercase", () => { + assert.deepEqual(resolveRequestedLabel("agent/s/Release-Notes"), { + route: "skill", + skill: "release-notes", + }); +}); + +test("resolveRequestedLabel rejects unsupported or malformed labels", () => { + assert.equal(resolveRequestedLabel("bug"), null); + assert.equal(resolveRequestedLabel("agent/deploy"), null); + assert.equal(resolveRequestedLabel("agent/s/../../oops"), null); +}); + +// --- applyDispatchPolicy --- + +test("applyDispatchPolicy requires approval for triaged implement decisions", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"implement","needs_approval":false,"summary":"s","issue_title":"t","issue_body":"b"}'), + "issue", + ); + assert.equal(d.needsApproval, true); +}); + +test("applyDispatchPolicy skips approval gate for explicit implement requests", () => { + const d = applyDispatchPolicy( + buildRequestedRouteDecision("implement", "@sepo-agent /implement add foo"), + "issue", + "MEMBER", + undefined, + false, + true, + ); + assert.equal(d.route, "implement"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy requires approval for triaged create-action decisions", () => { + const d = applyDispatchPolicy( + normalizeDispatch( + '{"route":"create-action","needs_approval":false,"summary":"s","issue_title":"t","issue_body":"b"}', + ), + "issue", + ); + assert.equal(d.route, "create-action"); + assert.equal(d.needsApproval, true); +}); + +test("applyDispatchPolicy skips approval gate for explicit create-action requests", () => { + const d = applyDispatchPolicy( + buildRequestedRouteDecision("create-action", "@sepo-agent /create-action monitor"), + "issue", + "MEMBER", + undefined, + false, + true, + ); + assert.equal(d.route, "create-action"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy denies explicit implement when access policy restricts the route", () => { + // Explicit /implement bypasses the approval gate but must still honor the + // access policy — isExplicit=true does not mean access-unrestricted. + const d = applyDispatchPolicy( + buildRequestedRouteDecision("implement", "@sepo-agent /implement add foo"), + "issue", + "CONTRIBUTOR", + parseAccessPolicy( + JSON.stringify({ + route_overrides: { + implement: ["OWNER", "MEMBER"], + }, + }), + ), + false, + true, + ); + assert.equal(d.route, "unsupported"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy dispatches fix-pr on PR without approval", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"fix-pr","needs_approval":true,"summary":"fix"}'), + "pull_request", + "MEMBER", + ); + assert.equal(d.route, "fix-pr"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy overrides model approval for fix-pr on PR", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"fix-pr","needs_approval":true,"summary":"fix it"}'), + "pull_request", + "OWNER", + ); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy uses default private repo access for fix-pr", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"fix-pr","summary":"fix"}'), + "pull_request", + "CONTRIBUTOR", + ); + assert.equal(d.route, "fix-pr"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy dispatches review on PR without approval", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"review","summary":"review it"}'), + "pull_request", + "MEMBER", + ); + assert.equal(d.route, "review"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy dispatches orchestrate on issue without approval", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"orchestrate","summary":"orchestrate"}'), + "issue", + "MEMBER", + ); + assert.equal(d.route, "orchestrate"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy rejects orchestrate requests outside issues and pull requests", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"orchestrate","summary":"orchestrate"}'), + "discussion", + ); + assert.equal(d.route, "unsupported"); +}); + +test("applyDispatchPolicy rejects review requests outside pull requests", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"review","summary":"review it"}'), + "issue", + ); + assert.equal(d.route, "unsupported"); +}); + +test("applyDispatchPolicy rejects fix-pr requests outside pull requests", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"fix-pr","summary":"fix"}'), + "issue", + ); + assert.equal(d.route, "unsupported"); +}); + +test("applyDispatchPolicy keeps skill requests as immediate inline runs", () => { + const d = applyDispatchPolicy( + buildRequestedRouteDecision("skill", "agent/s/release-notes"), + "issue", + ); + assert.equal(d.route, "skill"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy rejects routes disallowed by configured access policy", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"review","summary":"review it"}'), + "pull_request", + "CONTRIBUTOR", + parseAccessPolicy( + JSON.stringify({ + route_overrides: { + review: ["OWNER", "MEMBER", "COLLABORATOR"], + }, + }), + ), + ); + assert.equal(d.route, "unsupported"); + assert.match(d.summary, /OWNER, MEMBER, COLLABORATOR/); +}); + +test("applyDispatchPolicy allows contributors by default for public repos", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"answer","summary":"answer it"}'), + "issue", + "CONTRIBUTOR", + parseAccessPolicy(""), + true, + ); + assert.equal(d.route, "answer"); + assert.equal(d.needsApproval, false); +}); + +test("applyDispatchPolicy allows route overrides to widen public repo access", () => { + const d = applyDispatchPolicy( + normalizeDispatch('{"route":"fix-pr","summary":"fix it"}'), + "pull_request", + "CONTRIBUTOR", + parseAccessPolicy( + JSON.stringify({ + route_overrides: { + "fix-pr": ["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR"], + }, + }), + ), + true, + ); + assert.equal(d.route, "fix-pr"); + assert.equal(d.needsApproval, false); +}); diff --git a/.agent/src/__tests__/update-source-resolver-shell.test.ts b/.agent/src/__tests__/update-source-resolver-shell.test.ts new file mode 100644 index 0000000..1c641a1 --- /dev/null +++ b/.agent/src/__tests__/update-source-resolver-shell.test.ts @@ -0,0 +1,127 @@ +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { spawnSync } from "node:child_process"; +import { test } from "node:test"; +import { strict as assert } from "node:assert"; + +function runUpdateSourceResolver( + mode: "latest-release" | "manual" | "no-release" | "release-error", + extraEnv: Record = {}, +) { + const tempDir = mkdtempSync(join(tmpdir(), "update-source-resolver-")); + const binDir = join(tempDir, "bin"); + const outputFile = join(tempDir, "outputs.txt"); + const callLog = join(tempDir, "gh-calls.txt"); + const ghPath = join(binDir, "gh"); + mkdirSync(binDir); + writeFileSync(callLog, ""); + writeFileSync( + ghPath, + [ + "#!/usr/bin/env bash", + "set -euo pipefail", + "printf '%s\\n' \"$*\" >> \"${GH_STUB_CALL_LOG}\"", + "if [ \"${1:-}\" != \"api\" ]; then", + " echo \"unexpected gh invocation: $*\" >&2", + " exit 1", + "fi", + "case \"${GH_STUB_MODE}:${2:-}\" in", + " latest-release:repos/self-evolving/repo/releases?per_page=100)", + " printf '%s\\n' '[{\"tag_name\":\"v0.2.0\",\"html_url\":\"https://github.com/self-evolving/repo/releases/tag/v0.2.0\",\"draft\":false,\"prerelease\":false}]'", + " ;;", + " latest-release:repos/self-evolving/repo/commits/v0.2.0)", + " printf '%s\\n' '{\"sha\":\"abc123release\"}'", + " ;;", + " manual:repos/self-evolving/repo/commits/main)", + " printf '%s\\n' '{\"sha\":\"def456manual\"}'", + " ;;", + " no-release:repos/self-evolving/repo/releases?per_page=100)", + " printf '%s\\n' '[]'", + " ;;", + " no-release:repos/self-evolving/repo/commits/main)", + " printf '%s\\n' '{\"sha\":\"fed789fallback\"}'", + " ;;", + " release-error:repos/self-evolving/repo/releases?per_page=100)", + " echo \"server unavailable\" >&2", + " exit 1", + " ;;", + " *)", + " echo \"unexpected gh invocation for ${GH_STUB_MODE}: $*\" >&2", + " exit 1", + " ;;", + "esac", + ].join("\n") + "\n", + ); + chmodSync(ghPath, 0o755); + + const result = spawnSync("bash", ["scripts/resolve-update-source.sh"], { + cwd: process.cwd().endsWith(".agent") ? process.cwd() : join(process.cwd(), ".agent"), + env: { + ...process.env, + DEFAULT_UPDATE_SOURCE_REF: "main", + GH_STUB_CALL_LOG: callLog, + GH_STUB_MODE: mode, + GH_TOKEN: "test-token", + GITHUB_OUTPUT: outputFile, + PATH: `${binDir}:${process.env.PATH || ""}`, + UPDATE_SOURCE_REPO: "self-evolving/repo", + UPDATE_SOURCE_REF: "", + ...extraEnv, + }, + encoding: "utf8", + }); + const outputText = result.status === 0 ? readFileSync(outputFile, "utf8") : ""; + const calls = readFileSync(callLog, "utf8"); + const payload = result.stdout.trim() ? JSON.parse(result.stdout) : null; + return { calls, outputText, payload, result }; +} + +test("update source resolver defaults to the latest stable release tag", () => { + const { calls, outputText, payload, result } = runUpdateSourceResolver("latest-release"); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.sourceRef, "v0.2.0"); + assert.equal(payload.sourceSha, "abc123release"); + assert.equal(payload.sourceKind, "latest-release"); + assert.equal(payload.fallback, false); + assert.match(calls, /repos\/self-evolving\/repo\/releases\?per_page=100/); + assert.match(calls, /repos\/self-evolving\/repo\/commits\/v0\.2\.0/); + assert.match(outputText, /source_ref<<[\s\S]*v0\.2\.0/); + assert.match(outputText, /source_sha<<[\s\S]*abc123release/); +}); + +test("update source resolver preserves manual source_ref overrides", () => { + const { calls, payload, result } = runUpdateSourceResolver("manual", { UPDATE_SOURCE_REF: "main" }); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.sourceRef, "main"); + assert.equal(payload.sourceSha, "def456manual"); + assert.equal(payload.sourceKind, "manual"); + assert.equal(payload.fallback, false); + assert.doesNotMatch(calls, /releases/); + assert.match(calls, /repos\/self-evolving\/repo\/commits\/main/); +}); + +test("update source resolver falls back to main when no release exists", () => { + const { outputText, payload, result } = runUpdateSourceResolver("no-release"); + + assert.equal(result.status, 0, result.stderr); + assert.equal(payload.sourceRef, "main"); + assert.equal(payload.sourceSha, "fed789fallback"); + assert.equal(payload.sourceKind, "fallback-main"); + assert.equal(payload.fallback, true); + assert.match(payload.reason, /no stable Sepo release found; falling back to main/); + assert.match(outputText, /fallback<<[\s\S]*true/); + assert.match(outputText, /reason<<[\s\S]*no stable Sepo release found/); +}); + +test("update source resolver fails when release listing fails", () => { + const { calls, payload, result } = runUpdateSourceResolver("release-error"); + + assert.notEqual(result.status, 0); + assert.equal(payload, null); + assert.match(result.stderr, /could not list stable releases for self-evolving\/repo/); + assert.match(calls, /repos\/self-evolving\/repo\/releases\?per_page=100/); + assert.doesNotMatch(calls, /repos\/self-evolving\/repo\/commits\/main/); +}); diff --git a/.agent/src/__tests__/verify.test.ts b/.agent/src/__tests__/verify.test.ts new file mode 100644 index 0000000..67664ca --- /dev/null +++ b/.agent/src/__tests__/verify.test.ts @@ -0,0 +1,83 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { strict as assert } from "node:assert"; +import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; + +import { shouldRunVerification } from "../verify.js"; + +function git(cwd: string, args: string[]): string { + return execFileSync("git", args, { + cwd, + stdio: ["pipe", "pipe", "pipe"], + }).toString("utf8").trim(); +} + +function runVerifier(cwd: string, env: Record = {}) { + return spawnSync("bash", [".agent/scripts/post-agent-verify.sh"], { + cwd, + env: { ...process.env, ...env }, + encoding: "utf8", + }); +} + +test("shouldRunVerification skips unchanged clean runs", () => { + assert.equal(shouldRunVerification(false, false), false); +}); + +test("shouldRunVerification runs for dirty worktrees", () => { + assert.equal(shouldRunVerification(true, false), true); +}); + +test("shouldRunVerification runs for clean branch head updates", () => { + assert.equal(shouldRunVerification(false, true), true); +}); + +test("post-agent-verify uses VERIFY_BASE_SHA for clean history-only workflow changes", () => { + const repo = mkdtempSync(join(tmpdir(), "post-agent-verify-")); + try { + mkdirSync(join(repo, ".agent", "scripts"), { recursive: true }); + mkdirSync(join(repo, ".github", "workflows"), { recursive: true }); + cpSync( + join(process.cwd(), "scripts", "post-agent-verify.sh"), + join(repo, ".agent", "scripts", "post-agent-verify.sh"), + ); + + git(repo, ["init"]); + git(repo, ["config", "user.name", "Test User"]); + git(repo, ["config", "user.email", "test@example.com"]); + + writeFileSync( + join(repo, ".github", "workflows", "ci.yml"), + [ + "name: CI", + "on: workflow_dispatch", + "jobs:", + " check:", + " runs-on: ubuntu-latest", + " steps:", + " - run: echo ok", + "", + ].join("\n"), + "utf8", + ); + git(repo, ["add", "."]); + git(repo, ["commit", "-m", "seed workflow"]); + const baseSha = git(repo, ["rev-parse", "HEAD"]); + + writeFileSync(join(repo, ".github", "workflows", "ci.yml"), "name: [unterminated\n", "utf8"); + git(repo, ["add", ".github/workflows/ci.yml"]); + git(repo, ["commit", "-m", "break workflow yaml"]); + assert.equal(git(repo, ["status", "--porcelain"]), ""); + + const result = runVerifier(repo, { VERIFY_BASE_SHA: baseSha }); + assert.notEqual( + result.status, + 0, + `history-aware verification should inspect changed workflow files\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`, + ); + } finally { + rmSync(repo, { recursive: true, force: true }); + } +}); diff --git a/.agent/src/access-policy.ts b/.agent/src/access-policy.ts new file mode 100644 index 0000000..9eb9a73 --- /dev/null +++ b/.agent/src/access-policy.ts @@ -0,0 +1,130 @@ +const VALID_ASSOCIATIONS = new Set([ + "OWNER", + "MEMBER", + "COLLABORATOR", + "CONTRIBUTOR", + "FIRST_TIME_CONTRIBUTOR", + "FIRST_TIMER", + "MANNEQUIN", + "NONE", +]); + +const VALID_ROUTE_KEY = /^[a-z0-9][a-z0-9._-]*$/; + +const DEFAULT_PRIVATE_ALLOWED_ASSOCIATIONS = [ + "OWNER", + "MEMBER", + "COLLABORATOR", + "CONTRIBUTOR", +] as const; + +const DEFAULT_PUBLIC_ALLOWED_ASSOCIATIONS = [ + "OWNER", + "MEMBER", + "COLLABORATOR", + "CONTRIBUTOR", +] as const; + +export interface AccessPolicy { + defaultAllowedAssociations?: readonly string[]; + routeOverrides: Record; +} + +function normalizeAssociationList( + value: unknown, + label: string, +): string[] { + if (!Array.isArray(value)) { + throw new Error(`${label} must be an array`); + } + + const normalized = value.map((entry) => String(entry || "").trim().toUpperCase()); + if (normalized.length === 0) { + throw new Error(`${label} must contain at least one author association`); + } + + if (normalized.some((entry) => !VALID_ASSOCIATIONS.has(entry))) { + throw new Error(`${label} contains unsupported author associations`); + } + + return [...new Set(normalized)]; +} + +export function isKnownAuthorAssociation(association: string): boolean { + return VALID_ASSOCIATIONS.has(String(association || "").trim().toUpperCase()); +} + +export function parseAccessPolicy(raw: string): AccessPolicy { + const text = String(raw || "").trim(); + if (!text) { + return { routeOverrides: {} }; + } + + const payload = JSON.parse(text) as Record; + if (!payload || typeof payload !== "object" || Array.isArray(payload)) { + throw new Error("Access policy must be a JSON object"); + } + + const policy: AccessPolicy = { routeOverrides: {} }; + + if ("allowed_associations" in payload) { + policy.defaultAllowedAssociations = normalizeAssociationList( + payload.allowed_associations, + "allowed_associations", + ); + } + + if ("route_overrides" in payload) { + const routePolicy = payload.route_overrides; + if (!routePolicy || typeof routePolicy !== "object" || Array.isArray(routePolicy)) { + throw new Error("route_overrides must be an object"); + } + + for (const [route, associations] of Object.entries(routePolicy)) { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (!VALID_ROUTE_KEY.test(normalizedRoute)) { + throw new Error(`Invalid route override key in access policy: ${normalizedRoute || "missing"}`); + } + policy.routeOverrides[normalizedRoute] = normalizeAssociationList( + associations, + `route_overrides.${normalizedRoute}`, + ); + } + } + + return policy; +} + +export function getAllowedAssociationsForRoute( + policy: AccessPolicy, + route: string, + isPublicRepo: boolean, +): string[] { + const normalizedRoute = String(route || "").trim().toLowerCase(); + const configuredRoute = normalizedRoute + ? policy.routeOverrides[normalizedRoute] + : undefined; + if (configuredRoute) { + return [...configuredRoute]; + } + + if (policy.defaultAllowedAssociations) { + return [...policy.defaultAllowedAssociations]; + } + + return isPublicRepo + ? [...DEFAULT_PUBLIC_ALLOWED_ASSOCIATIONS] + : [...DEFAULT_PRIVATE_ALLOWED_ASSOCIATIONS]; +} + +export function isAssociationAllowedForRoute( + policy: AccessPolicy, + route: string, + association: string, + isPublicRepo: boolean, +): boolean { + const normalizedAssociation = String(association || "").trim().toUpperCase(); + return getAllowedAssociationsForRoute(policy, route, isPublicRepo).includes( + normalizedAssociation, + ); +} diff --git a/.agent/src/acpx-adapter.ts b/.agent/src/acpx-adapter.ts new file mode 100644 index 0000000..80fb718 --- /dev/null +++ b/.agent/src/acpx-adapter.ts @@ -0,0 +1,810 @@ +// Thin acpx adapter. +// +// Wraps acpx CLI calls with: preflight checks, session naming via +// `sessions ensure`, identity reconciliation, per-route permission mode, +// and output mode selection. +// +// Resume policy: +// - session mode is explicit (`exec` or `persistent`) +// - workflows provide `session_policy`; the adapter does not hard-code routes +// - the adapter reports whether the session was resumed, freshly created, +// fell back to fresh after resume failure, or failed before the run. + +import { execFileSync, spawnSync } from "node:child_process"; +import { randomBytes } from "node:crypto"; +import { closeSync, mkdtempSync, openSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +// --- Types --- + +export interface AcpxRunOptions { + /** The agent to use (e.g., "codex", "claude") */ + agent: string; + /** The prompt text */ + prompt: string; + /** Smaller prompt for a successfully resumed destination session. */ + continuationPrompt?: string; + /** Working directory for the acpx process */ + cwd: string; + /** Explicit execution mode: one-shot exec or persistent named session */ + sessionMode: "exec" | "persistent"; + /** Thread key for session naming (persistent lanes only) */ + threadKey?: string; + /** Permission mode override */ + permissionMode?: "approve-all" | "approve-reads" | "deny-all"; + /** Timeout in seconds */ + timeout?: number; + /** Optional Codex thought level for session-backed runs. */ + thoughtLevel?: string; + /** Allow exec lanes to use a fresh session for non-resumable artifacts. */ + preserveExecSession?: boolean; + /** Allow exec lanes to use a fresh Codex session only to apply thoughtLevel. */ + preserveExecThoughtLevel?: boolean; + /** Prior ACP session ID to resume (when workflow opts in) */ + resumeSessionId?: string; + /** Extra environment variables */ + env?: Record; +} + +export type PermissionMode = "approve-all" | "approve-reads" | "deny-all"; + +export type SessionEnsureOutcome = + | { kind: "not_applicable" } + | { kind: "fresh" } + | { kind: "resumed"; resumedFromSessionId: string } + | { kind: "resume_fallback"; resumedFromSessionId: string; error: string } + | { kind: "failed"; error: string; resumedFromSessionId?: string }; + +export interface AcpxRunResult { + exitCode: number; + /** Final assistant message extracted from the session */ + stdout: string; + /** Raw acpx stdout (typically NDJSON) */ + rawStdout: string; + stderr: string; + /** Compacted session log (merged tokens, structured events) */ + sessionLog: string; + sessionName?: string; + /** Structured outcome of session ensure/resume before the run */ + sessionEnsureOutcome: SessionEnsureOutcome; +} + +export interface PreflightResult { + ok: boolean; + missing: string[]; +} + +export interface SessionIdentity { + acpxRecordId: string; + acpxSessionId: string; +} + +export interface SessionIdentityReadResult { + identity: SessionIdentity | null; + error: string; +} + +// --- Route configuration --- + +/** Default persistent session mode for agents that support Codex-style modes. */ +const PERSISTENT_SESSION_MODE = "full-access"; +const CLAUDE_BYPASS_MODE = "bypassPermissions"; +const DEFAULT_PERMISSION_MODE: PermissionMode = "approve-all"; +const ACPX_MAX_BUFFER = 50 * 1024 * 1024; // 50 MB +const TRANSIENT_EXEC_SESSION_BYTES = 6; + +export interface FileCaptureRunOptions { + command: string; + args: string[]; + cwd: string; + env?: NodeJS.ProcessEnv; + /** Timeout in seconds */ + timeout?: number; +} + +export interface FileCaptureRunResult { + exitCode: number; + stdout: string; + stderr: string; +} + +/** + * Runs a command synchronously while streaming stdout/stderr to temp files. + * + * This avoids the `execFileSync` maxBuffer cap for large agent/tool output, + * but still returns the captured text to the caller after the process exits. + */ +export function runCommandWithFileCapture(options: FileCaptureRunOptions): FileCaptureRunResult { + const captureDir = mkdtempSync(join(tmpdir(), "acpx-capture-")); + const stdoutPath = join(captureDir, "stdout.log"); + const stderrPath = join(captureDir, "stderr.log"); + let stdoutFd: number | null = null; + let stderrFd: number | null = null; + + try { + stdoutFd = openSync(stdoutPath, "w"); + stderrFd = openSync(stderrPath, "w"); + + const result = spawnSync(options.command, options.args, { + cwd: options.cwd, + env: options.env, + stdio: ["ignore", stdoutFd, stderrFd], + timeout: options.timeout ? options.timeout * 1000 : undefined, + }); + + closeSync(stdoutFd); + stdoutFd = null; + closeSync(stderrFd); + stderrFd = null; + + let stderr = readFileSync(stderrPath, "utf8"); + const stdout = readFileSync(stdoutPath, "utf8"); + + if (result.error) { + const errorMessage = result.error.message || String(result.error); + stderr = stderr ? `${stderr}\n${errorMessage}` : errorMessage; + } + + return { + exitCode: + typeof result.status === "number" + ? result.status + : result.error || result.signal + ? 1 + : 0, + stdout, + stderr, + }; + } finally { + if (stdoutFd !== null) { + try { + closeSync(stdoutFd); + } catch { + // Already closed. + } + } + if (stderrFd !== null) { + try { + closeSync(stderrFd); + } catch { + // Already closed. + } + } + rmSync(captureDir, { recursive: true, force: true }); + } +} + +// --- Preflight --- + +function commandExists(cmd: string): boolean { + try { + execFileSync("command", ["-v", cmd], { stdio: "pipe", shell: true }); + return true; + } catch { + return false; + } +} + +/** + * Verifies that required tools are available on the runner. + */ +export function preflight(): PreflightResult { + const required = ["acpx", "gh", "git"]; + const missing = required.filter((cmd) => !commandExists(cmd)); + return { ok: missing.length === 0, missing }; +} + +// --- Session naming --- + +/** + * Converts a thread key into a safe acpx session name. + * acpx session names should be short, filesystem-safe identifiers. + */ +export function sessionNameFromThreadKey(threadKey: string): string { + // thread_key format: repo:target_kind:target_number:route:lane + // session name: target_kind-target_number-route-lane + const parts = threadKey.split(":"); + if (parts.length >= 5) { + return parts.slice(1).join("-"); + } + return threadKey.replace(/[/:]/g, "-"); +} + +function transientSessionNameForExec(threadKey: string | undefined): string { + const base = threadKey ? sessionNameFromThreadKey(threadKey) : "exec"; + return `${base}-exec-${randomBytes(TRANSIENT_EXEC_SESSION_BYTES).toString("hex")}`; +} + +function isCodexAgent(agent: string): boolean { + return agent.trim().toLowerCase() === "codex"; +} + +export function buildAcpxArgs(options: { + agent: string; + prompt: string; + permissionMode: PermissionMode; + timeout?: number; + sessionName?: string; + isExecRoute: boolean; +}): string[] { + const args: string[] = []; + + // acpx requires global flags before the agent token. + args.push(`--${options.permissionMode}`); + args.push("--format", "json", "--json-strict"); + args.push("--suppress-reads"); + if (options.timeout) { + args.push("--timeout", String(options.timeout)); + } + + args.push(options.agent); + + if (options.isExecRoute || !options.sessionName) { + args.push("exec"); + } else { + args.push("prompt", "-s", options.sessionName); + } + + args.push(options.prompt); + return args; +} + +export function parsePermissionModeOrSetDefault(value: string | undefined): PermissionMode { + const v = value?.trim(); + if (v === "approve-all" || v === "approve-reads" || v === "deny-all") { + return v; + } + return DEFAULT_PERMISSION_MODE; +} + +export function selectPromptForSessionOutcome(options: { + fullPrompt: string; + continuationPrompt?: string; + outcome: SessionEnsureOutcome; +}): string { + if (options.outcome.kind === "resumed" && options.continuationPrompt) { + return options.continuationPrompt; + } + return options.fullPrompt; +} + +export interface SessionSetupCommand { + label: string; + args: string[]; +} + +export function buildSessionSetupCommands(options: { + agent: string; + sessionName?: string; + thoughtLevel?: string; + permissionMode?: PermissionMode; +}): SessionSetupCommand[] { + if (!options.sessionName) { + return []; + } + + const normalizedAgent = options.agent.trim().toLowerCase(); + if (normalizedAgent === "claude") { + if (options.permissionMode === "approve-all") { + return [ + { + label: "set-mode", + args: [options.agent, "set-mode", "-s", options.sessionName, CLAUDE_BYPASS_MODE], + }, + ]; + } + return []; + } + + const commands: SessionSetupCommand[] = []; + const thoughtLevel = options.thoughtLevel?.trim(); + if (thoughtLevel) { + commands.push({ + label: "set thought_level", + args: [options.agent, "set", "-s", options.sessionName, "thought_level", thoughtLevel], + }); + } + + commands.push({ + label: "set-mode", + args: [options.agent, "set-mode", "-s", options.sessionName, PERSISTENT_SESSION_MODE], + }); + + return commands; +} + +export function parseSessionIdentity(raw: string): SessionIdentity | null { + try { + const data = JSON.parse(raw) as Record; + + const acpxRecordId = + typeof data.acpxRecordId === "string" + ? data.acpxRecordId + : typeof data.recordId === "string" + ? data.recordId + : ""; + const acpxSessionId = + typeof data.acpSessionId === "string" + ? data.acpSessionId + : typeof data.acpxSessionId === "string" + ? data.acpxSessionId + : typeof data.sessionId === "string" + ? data.sessionId + : ""; + + if (!acpxRecordId || !acpxSessionId) { + return null; + } + return { acpxRecordId, acpxSessionId }; + } catch { + return null; + } +} + +/** + * Ensures a named session exists via `acpx sessions ensure`. + * + * When `resumeSessionId` is provided, first attempts to resume that ACP + * session. If resume fails (expired session, new runner, etc.), falls back + * to creating a fresh session under the same name. + * + * Returns a structured outcome so the runtime can distinguish: + * - resumed successfully + * - resumed failed, fresh fallback used + * - no resume attempted + * - failed before the run + */ +function ensureSession( + agent: string, + sessionName: string, + cwd: string, + env: NodeJS.ProcessEnv, + resumeSessionId?: string, +): SessionEnsureOutcome { + if (resumeSessionId) { + try { + execFileSync( + "acpx", + [agent, "sessions", "ensure", "--name", sessionName, "--resume-session", resumeSessionId], + { + cwd, + env, + stdio: "pipe", + maxBuffer: ACPX_MAX_BUFFER, + }, + ); + return { kind: "resumed", resumedFromSessionId: resumeSessionId }; + } catch (err: unknown) { + const resumeError = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + try { + execFileSync("acpx", [agent, "sessions", "ensure", "--name", sessionName], { + cwd, + env, + stdio: "pipe", + maxBuffer: ACPX_MAX_BUFFER, + }); + return { + kind: "resume_fallback", + resumedFromSessionId: resumeSessionId, + error: resumeError, + }; + } catch (freshErr: unknown) { + const freshError = (freshErr as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(freshErr); + return { + kind: "failed", + resumedFromSessionId: resumeSessionId, + error: `resume failed: ${resumeError}\nfresh ensure failed: ${freshError}`, + }; + } + } + } + + try { + execFileSync("acpx", [agent, "sessions", "ensure", "--name", sessionName], { + cwd, + env, + stdio: "pipe", + maxBuffer: ACPX_MAX_BUFFER, + }); + return { kind: "fresh" }; + } catch (err: unknown) { + const error = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + return { kind: "failed", error }; + } +} + +function createTransientSession( + agent: string, + sessionName: string, + cwd: string, + env: NodeJS.ProcessEnv, +): SessionEnsureOutcome { + try { + execFileSync("acpx", [agent, "sessions", "new", "--name", sessionName], { + cwd, + env, + stdio: "pipe", + maxBuffer: ACPX_MAX_BUFFER, + }); + return { kind: "fresh" }; + } catch (err: unknown) { + const error = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + return { kind: "failed", error }; + } +} + +function runSessionSetupCommands(options: { + agent: string; + sessionName: string; + thoughtLevel?: string; + permissionMode: PermissionMode; + cwd: string; + env: NodeJS.ProcessEnv; +}): { ok: true } | { ok: false; status?: number; stderr: string } { + try { + for (const command of buildSessionSetupCommands({ + agent: options.agent, + sessionName: options.sessionName, + thoughtLevel: options.thoughtLevel, + permissionMode: options.permissionMode, + })) { + execFileSync("acpx", command.args, { + cwd: options.cwd, + env: options.env, + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: ACPX_MAX_BUFFER, + }); + } + return { ok: true }; + } catch (err: unknown) { + const error = err as { status?: number; stderr?: Buffer }; + return { + ok: false, + status: error.status, + stderr: error.stderr?.toString("utf8") ?? String(err), + }; + } +} + +// --- NDJSON parsing --- + +/** + * Extracts the final assistant message from a compacted session log. + * Returns the last `message` entry — reasoning traces are in the JSONL. + */ +export function extractAssistantText(compactedLog: string): string { + let lastMessage = ""; + for (const line of compactedLog.split("\n")) { + if (!line.trim()) continue; + try { + const entry = JSON.parse(line) as { type?: string; text?: string }; + if (entry.type === "message" && entry.text) { + lastMessage = entry.text; + } + } catch { + // skip + } + } + return lastMessage; +} + +/** + * Compacts raw acpx NDJSON into a clean session log. + * + * - Merges streaming `agent_message_chunk` tokens into one entry per turn + * - Keeps tool_call events (with name/status) + * - Keeps usage_update events + * - Extracts session metadata from the verbose init/session payloads + * - Drops everything else (protocol handshake, model lists, etc.) + */ +export function compactSessionLog(ndjson: string): string { + const entries: string[] = []; + let currentText = ""; + let sessionId = ""; + + function flushText(): void { + if (currentText) { + entries.push(JSON.stringify({ type: "message", text: currentText })); + currentText = ""; + } + } + + for (const line of ndjson.split("\n")) { + if (!line.trim()) continue; + try { + const event = JSON.parse(line) as Record; + + // Extract sessionId from session/new response + const result = event.result as Record | undefined; + if (result?.sessionId && !sessionId) { + sessionId = String(result.sessionId); + const models = result.models as Record | undefined; + entries.push(JSON.stringify({ + type: "session", + sessionId, + model: models?.currentModelId ?? null, + })); + continue; + } + + const update = (event.params as Record | undefined) + ?.update as Record | undefined; + if (!update?.sessionUpdate) continue; + + const updateType = update.sessionUpdate; + + if (updateType === "agent_message_chunk") { + const content = update.content as Record | undefined; + if (content?.type === "text" && content.text) { + currentText += String(content.text); + } + } else if (updateType === "tool_call" || updateType === "tool_call_update") { + flushText(); + entries.push(JSON.stringify({ + type: updateType, + name: update.name ?? update.title ?? null, + status: update.status ?? null, + })); + } else if (updateType === "usage_update") { + flushText(); + entries.push(JSON.stringify({ + type: "usage", + used: update.used ?? null, + size: update.size ?? null, + })); + } + } catch { + // Preserve unparseable lines so schema drift doesn't silently vanish + entries.push(JSON.stringify({ type: "parse_error", raw: line.slice(0, 500) })); + } + } + flushText(); + + // Append stop reason from final RPC response + const lastLine = ndjson.trimEnd().split("\n").pop(); + if (lastLine) { + try { + const last = JSON.parse(lastLine) as Record; + const lastResult = last.result as Record | undefined; + if (lastResult?.stopReason) { + entries.push(JSON.stringify({ type: "done", stopReason: lastResult.stopReason })); + } + } catch { /* skip */ } + } + + return entries.join("\n") + "\n"; +} + +const SESSION_LOG_MAX_MESSAGE_CHARS = 2000; + +/** + * Formats a compacted session log for human-readable display in CI logs. + * Message text is truncated to SESSION_LOG_MAX_MESSAGE_CHARS per entry. + */ +export function formatSessionLogForDisplay(sessionLog: string): string { + const lines: string[] = []; + for (const raw of sessionLog.split("\n")) { + if (!raw.trim()) continue; + try { + const entry = JSON.parse(raw) as Record; + switch (entry.type) { + case "session": + lines.push(`[session] ${entry.model ?? "unknown"} ${entry.sessionId ?? ""}`); + break; + case "message": { + const text = String(entry.text || ""); + const display = text.length > SESSION_LOG_MAX_MESSAGE_CHARS + ? text.slice(0, SESSION_LOG_MAX_MESSAGE_CHARS) + `... (${text.length} chars)` + : text; + lines.push(`[message] ${display}`); + break; + } + case "tool_call": + lines.push(`[tool] ${entry.name ?? "unknown"} (${entry.status ?? "?"})`); + break; + case "tool_call_update": + if (entry.status) { + lines.push(`[tool] ${entry.name ?? " ↳"} (${entry.status})`); + } + break; + case "usage": + lines.push(`[usage] ${entry.used ?? "?"} tokens`); + break; + case "done": + lines.push(`[done] ${entry.stopReason ?? "unknown"}`); + break; + case "parse_error": + lines.push(`[warn] unparseable line: ${String(entry.raw ?? "").slice(0, 200)}`); + break; + default: + break; + } + } catch { + // skip + } + } + return lines.join("\n"); +} + +export function tailForLog(value: string, maxChars: number): string { + if (value.length <= maxChars) { + return value; + } + return `[truncated ${value.length - maxChars} chars]\n${value.slice(-maxChars)}`; +} + +// --- Runner --- + +/** + * Runs an acpx prompt and returns the result. + * + * CLI argv ordering: acpx [global-flags] [subcommand-args] [prompt] + */ +export function runAcpx(options: AcpxRunOptions): AcpxRunResult { + const { + agent, + prompt, + continuationPrompt, + cwd, + sessionMode, + threadKey, + timeout, + thoughtLevel, + preserveExecSession, + preserveExecThoughtLevel, + resumeSessionId, + env: extraEnv, + } = options; + + const permissionMode = options.permissionMode ?? DEFAULT_PERMISSION_MODE; + const isExecRoute = sessionMode === "exec"; + const env = { ...process.env, ...extraEnv }; + const normalizedThoughtLevel = thoughtLevel?.trim(); + const needsTransientExecSession = + preserveExecSession === true || + (preserveExecThoughtLevel === true && + isExecRoute && + isCodexAgent(agent) && + Boolean(normalizedThoughtLevel)); + let sessionName: string | undefined; + let sessionEnsureOutcome: SessionEnsureOutcome = { kind: "not_applicable" }; + if (isExecRoute && needsTransientExecSession) { + sessionName = transientSessionNameForExec(threadKey); + sessionEnsureOutcome = createTransientSession(agent, sessionName, cwd, env); + if (sessionEnsureOutcome.kind === "failed") { + return { + exitCode: 1, + stdout: "", + rawStdout: "", + stderr: `session setup failed: ${sessionEnsureOutcome.error}`, + sessionLog: "", + sessionName, + sessionEnsureOutcome, + }; + } + const setupResult = runSessionSetupCommands({ + agent, + sessionName, + thoughtLevel: normalizedThoughtLevel, + permissionMode, + cwd, + env, + }); + if (!setupResult.ok) { + return { + exitCode: setupResult.status ?? 1, + stdout: "", + rawStdout: "", + stderr: `session setup failed: ${setupResult.stderr}`, + sessionLog: "", + sessionName, + sessionEnsureOutcome, + }; + } + } else if (isExecRoute || !threadKey) { + sessionName = undefined; + } else { + // Persistent lane: ensure session exists first + sessionName = sessionNameFromThreadKey(threadKey); + sessionEnsureOutcome = ensureSession(agent, sessionName, cwd, env, resumeSessionId); + if (sessionEnsureOutcome.kind === "failed") { + return { + exitCode: 1, + stdout: "", + rawStdout: "", + stderr: `session setup failed: ${sessionEnsureOutcome.error}`, + sessionLog: "", + sessionName, + sessionEnsureOutcome, + }; + } + const setupResult = runSessionSetupCommands({ + agent, + sessionName, + thoughtLevel, + permissionMode, + cwd, + env, + }); + if (!setupResult.ok) { + return { + exitCode: setupResult.status ?? 1, + stdout: "", + rawStdout: "", + stderr: `session setup failed: ${setupResult.stderr}`, + sessionLog: "", + sessionName, + sessionEnsureOutcome, + }; + } + } + const args = buildAcpxArgs({ + agent, + prompt: selectPromptForSessionOutcome({ + fullPrompt: prompt, + continuationPrompt, + outcome: sessionEnsureOutcome, + }), + permissionMode, + timeout, + sessionName, + isExecRoute: isExecRoute && !needsTransientExecSession, + }); + + const result = runCommandWithFileCapture({ + command: "acpx", + args, + cwd, + env, + timeout, + }); + + const sessionLog = compactSessionLog(result.stdout); + const stdout = extractAssistantText(sessionLog); + return { + exitCode: result.exitCode, + stdout, + rawStdout: result.stdout, + stderr: result.stderr, + sessionLog, + sessionName, + sessionEnsureOutcome, + }; +} + +/** + * Reads session metadata after a run to extract identity fields. + * Returns acpxRecordId and acpxSessionId if available. + */ +export function readSessionIdentityResult( + agent: string, + sessionName: string, + cwd: string, +): SessionIdentityReadResult { + try { + const result = runCommandWithFileCapture({ + command: "acpx", + args: ["--format", "json", agent, "sessions", "show", sessionName], + cwd, + }); + + if (result.exitCode !== 0) { + return { + identity: null, + error: result.stderr.trim() || `acpx sessions show exited with code ${result.exitCode}`, + }; + } + + const identity = parseSessionIdentity(result.stdout); + if (!identity) { + return { + identity: null, + error: "acpx session metadata did not include acpxRecordId and acpxSessionId", + }; + } + return { identity, error: "" }; + } catch (err: unknown) { + return { identity: null, error: err instanceof Error ? err.message : String(err) }; + } +} diff --git a/.agent/src/approval.ts b/.agent/src/approval.ts new file mode 100644 index 0000000..587c04f --- /dev/null +++ b/.agent/src/approval.ts @@ -0,0 +1,177 @@ +// Helpers for encoding, finding, and resolving comment-based approval requests +// left by the portal workflow before dispatching heavier follow-up workflows. + +import { DEFAULT_MENTION } from "./context.js"; +import { escapeRegex, stripNonLiveMentions } from "./mentions.js"; + +const APPROVAL_MARKER_RE = + //i; +const APPROVAL_STATUS_RE = //i; + +export interface PendingApproval { + comment: { id: string | number; body: string; created_at: string }; + request: Record; +} + +export interface ApprovalCommand { + requestId: string; +} + +function buildApprovalCommandRegex(mention: string): RegExp | null { + const trimmedMention = String(mention || "").trim(); + if (!trimmedMention) { + return null; + } + + return new RegExp( + `(?:^|\\s)${escapeRegex(trimmedMention)}\\s+\\/approve\\s+(req-[a-z0-9-]{4,})(?=$|\\s|[.!?])`, + "i", + ); +} + +function encodeApprovalMarkerPayload(data: Record): string { + return Buffer.from(JSON.stringify(data), "utf8").toString("base64url"); +} + +function decodeApprovalMarkerPayload(payload: string): Record { + const json = Buffer.from(payload, "base64url").toString("utf8"); + return JSON.parse(json) as Record; +} + +/** + * Encodes workflow dispatch metadata into a hidden HTML marker inside a comment. + */ +export function buildApprovalRequestMarker(data: Record): string { + return ``; +} + +/** + * Parses the hidden approval marker from a comment body when present. + */ +export function parseApprovalRequestMarker( + body: string, +): Record | null { + const text = String(body || ""); + const encodedMatch = text.match(APPROVAL_MARKER_RE); + try { + return encodedMatch ? decodeApprovalMarkerPayload(encodedMatch[1]) : null; + } catch { + return null; + } +} + +/** + * Reports whether the approval-request comment has already been resolved. + */ +export function isApprovalRequestAlreadySatisfied(body: string): boolean { + return APPROVAL_STATUS_RE.test(String(body || "")); +} + +/** + * Reports whether a comment is an agent-managed approval request/status comment. + */ +export function isAgentApprovalComment(body: string): boolean { + const text = String(body || ""); + return parseApprovalRequestMarker(text) !== null || isApprovalRequestAlreadySatisfied(text); +} + +/** + * Appends a human-readable approval note and a hidden satisfied marker. + */ +export function markApprovalRequestSatisfied( + body: string, + approver: string, + extra?: { + route?: string; + workflow?: string; + issueUrl?: string; + runUrl?: string; + }, +): string { + const action = extra?.workflow + ? `\`${extra.route || "follow-up"}\` via \`${extra.workflow}\`` + : `\`${extra?.route || "follow-up"}\``; + const trackingParts: string[] = []; + if (extra?.issueUrl) { + const issueNum = extra.issueUrl.match(/#?(\d+)$/)?.[1]; + trackingParts.push(issueNum ? `#${issueNum}` : extra.issueUrl); + } + if (extra?.runUrl) { + trackingParts.push(`[approval run](${extra.runUrl})`); + } + const tracking = trackingParts.length > 0 ? trackingParts.join(", ") : "\u2014"; + + const table = [ + "| Approved by | Action | Tracking |", + "|---|---|---|", + `| @${approver} | ${action} | ${tracking} |`, + ].join("\n"); + + return `${String(body || "").trim()}\n\n${table}\n\n\n`; +} + +/** + * Matches explicit approval commands understood by the portal. + */ +export function isApprovalCommand(body: string, mention = DEFAULT_MENTION): boolean { + return parseApprovalCommand(body, mention) !== null; +} + +/** + * Parses an approval command and extracts the referenced request ID. + */ +export function parseApprovalCommand( + body: string, + mention = DEFAULT_MENTION, +): ApprovalCommand | null { + const commandRe = buildApprovalCommandRegex(mention); + if (!commandRe) return null; + const match = stripNonLiveMentions(String(body || "")).match(commandRe); + if (!match) return null; + return { requestId: match[1].toLowerCase() }; +} + +/** + * Finds a specific unresolved approval request comment by request ID. + */ +export function findPendingRequestById( + comments: Array<{ + id?: string | number; + body?: string; + created_at?: string; + }>, + requestId: string, +): PendingApproval | null { + for (const comment of comments) { + const request = parseApprovalRequestMarker(comment.body || ""); + if (!request) continue; + if (String(request.request_id || "").toLowerCase() !== requestId.toLowerCase()) { + continue; + } + if (isApprovalRequestAlreadySatisfied(comment.body || "")) continue; + return { + comment: { + id: comment.id ?? "", + body: comment.body || "", + created_at: comment.created_at || "", + }, + request, + }; + } + + return null; +} + +/** + * Reports whether approving this request requires creating a new tracking + * issue first. Implementation-like requests from non-issue surfaces should do that. + */ +export function shouldCreateIssueFromApprovalRequest( + request: Record, +): boolean { + return ( + (request?.route === "implement" || request?.route === "create-action") && + request?.target_kind !== "issue" && + String(request?.issue_title || "").trim() !== "" + ); +} diff --git a/.agent/src/cli/add-label.ts b/.agent/src/cli/add-label.ts new file mode 100644 index 0000000..a488603 --- /dev/null +++ b/.agent/src/cli/add-label.ts @@ -0,0 +1,44 @@ +// CLI: add the fixed agent status label to a handled issue or PR. +// Usage: node .agent/dist/cli/add-label.js +// Env: AGENT_STATUS_LABEL_ENABLED, TARGET_KIND, TARGET_NUMBER, GITHUB_REPOSITORY +// Non-fatal: exits 0 even if label creation or application fails. + +import { addIssueLabel, addPrLabel, ensureLabel } from "../github.js"; + +const STATUS_LABEL = "agent"; +const STATUS_LABEL_COLOR = "0e8a16"; +const STATUS_LABEL_DESCRIPTION = "Handled by the agent"; + +const enabled = (process.env.AGENT_STATUS_LABEL_ENABLED || "").trim() === "true"; +const targetKind = process.env.TARGET_KIND || ""; +const targetNumberRaw = process.env.TARGET_NUMBER || ""; +const repo = process.env.GITHUB_REPOSITORY || undefined; +const targetNumber = Number.parseInt(targetNumberRaw, 10); + +if (!enabled) { + console.log("AGENT_STATUS_LABEL_ENABLED is not true; skipping status label."); +} else if (targetKind !== "issue" && targetKind !== "pull_request") { + console.log(`Target kind ${targetKind || "(empty)"} is not labelable; skipping status label.`); +} else if (!Number.isInteger(targetNumber) || targetNumber <= 0) { + console.log(`Target number ${targetNumberRaw || "(empty)"} is not valid; skipping status label.`); +} else { + try { + ensureLabel({ + name: STATUS_LABEL, + color: STATUS_LABEL_COLOR, + description: STATUS_LABEL_DESCRIPTION, + repo, + }); + + if (targetKind === "issue") { + addIssueLabel(targetNumber, STATUS_LABEL, repo); + } else { + addPrLabel(targetNumber, STATUS_LABEL, repo); + } + + console.log(`Added ${STATUS_LABEL} label to ${targetKind} #${targetNumber}.`); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.warn(`Could not add ${STATUS_LABEL} label to ${targetKind} #${targetNumber}: ${msg}`); + } +} diff --git a/.agent/src/cli/add-reaction.ts b/.agent/src/cli/add-reaction.ts new file mode 100644 index 0000000..cfc3900 --- /dev/null +++ b/.agent/src/cli/add-reaction.ts @@ -0,0 +1,22 @@ +// CLI: add a reaction to a GitHub node. +// Usage: node .agent/dist/cli/add-reaction.js +// Env: REACTION_SUBJECT_ID, REACTION_CONTENT (e.g., "EYES", "THUMBS_UP") +// Non-fatal: exits 0 even if the reaction fails. + +import { addReaction } from "../reactions.js"; + +const subjectId = process.env.REACTION_SUBJECT_ID || ""; +const content = process.env.REACTION_CONTENT || ""; + +if (!subjectId) { + console.log("No REACTION_SUBJECT_ID; skipping reaction."); +} else if (!content) { + console.log("No REACTION_CONTENT; skipping reaction."); +} else { + try { + addReaction(subjectId, content); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.warn(`Could not add ${content} reaction: ${msg}`); + } +} diff --git a/.agent/src/cli/apply-project-management-labels.ts b/.agent/src/cli/apply-project-management-labels.ts new file mode 100644 index 0000000..e6a0e5c --- /dev/null +++ b/.agent/src/cli/apply-project-management-labels.ts @@ -0,0 +1,76 @@ +#!/usr/bin/env node +// CLI: deterministically apply managed project-manager label changes. +// Env: BODY_FILE, GITHUB_REPOSITORY, AGENT_PROJECT_MANAGEMENT_DRY_RUN, +// AGENT_PROJECT_MANAGEMENT_APPLY_LABELS + +import { readFileSync } from "node:fs"; +import { + applyManagedLabelChange, + countManagedLabelOperations, + ensureManagedLabels, + parseManagedLabelPlan, +} from "../project-management-labels.js"; +import { setOutput } from "../output.js"; + +function boolEnv(name: string, fallback = false): boolean { + const value = (process.env[name] || "").trim().toLowerCase(); + if (!value) return fallback; + return ["1", "true", "yes", "on"].includes(value); +} + +function requiredEnv(name: string): string { + const value = process.env[name]?.trim() || ""; + if (!value) throw new Error(`${name} is required`); + return value; +} + +function appendStatus(summary: string, status: string): string { + return `${summary.trim()}\n\n### Managed Label Application\n\n${status}\n`; +} + +function main(): number { + try { + const bodyFile = requiredEnv("BODY_FILE"); + const repo = requiredEnv("GITHUB_REPOSITORY"); + const dryRun = boolEnv("AGENT_PROJECT_MANAGEMENT_DRY_RUN", true); + const applyLabels = boolEnv("AGENT_PROJECT_MANAGEMENT_APPLY_LABELS", true); + const summary = readFileSync(bodyFile, "utf8"); + const plan = parseManagedLabelPlan(summary); + + if (!plan.valid) { + throw new Error("Project management summary did not include a valid fenced JSON label_changes plan."); + } + + const operationCount = countManagedLabelOperations(plan.label_changes); + + if (dryRun || !applyLabels) { + const status = dryRun + ? `- Dry run is enabled; ${operationCount} managed label operation(s) were planned but not applied.` + : `- Label application is disabled; ${operationCount} managed label operation(s) were planned but not applied.`; + setOutput("labels_applied", "false"); + setOutput("operation_count", String(operationCount)); + setOutput("summary", appendStatus(summary, status)); + console.log(status); + return 0; + } + + if (operationCount > 0) { + ensureManagedLabels(repo); + for (const change of plan.label_changes) { + applyManagedLabelChange(change, repo); + } + } + + const status = `- Applied ${operationCount} managed priority/effort label operation(s).`; + setOutput("labels_applied", "true"); + setOutput("operation_count", String(operationCount)); + setOutput("summary", appendStatus(summary, status)); + console.log(status); + return 0; + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } +} + +process.exitCode = main(); diff --git a/.agent/src/cli/capture-pr-head.ts b/.agent/src/cli/capture-pr-head.ts new file mode 100644 index 0000000..44fecb7 --- /dev/null +++ b/.agent/src/cli/capture-pr-head.ts @@ -0,0 +1,33 @@ +// CLI: capture the current PR head SHA for workflows that need a stable reviewed head. +// Env: GITHUB_REPOSITORY, TARGET_NUMBER +// Outputs: head_sha + +import { fetchPrMeta } from "../github.js"; +import { setOutput } from "../output.js"; + +const repo = process.env.GITHUB_REPOSITORY || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || process.env.PR_NUMBER || ""); + +function warningMessage(err: unknown): string { + return err instanceof Error ? err.message : String(err); +} + +function captureReviewedHeadSha(): string { + try { + if (!repo || !Number.isFinite(targetNumber) || targetNumber <= 0) { + throw new Error("missing pull request target"); + } + + const meta = fetchPrMeta(targetNumber, repo); + if (!meta.headOid) { + throw new Error("could not resolve pull request head SHA"); + } + + return meta.headOid; + } catch (err: unknown) { + console.warn(`Reviewed head capture skipped: ${warningMessage(err)}`); + return ""; + } +} + +setOutput("head_sha", captureReviewedHeadSha()); diff --git a/.agent/src/cli/checkout-pr.ts b/.agent/src/cli/checkout-pr.ts new file mode 100644 index 0000000..07db52b --- /dev/null +++ b/.agent/src/cli/checkout-pr.ts @@ -0,0 +1,35 @@ +// CLI: fetch PR metadata and checkout the PR head branch. +// Usage: node .agent/dist/cli/checkout-pr.js +// Env: PR_NUMBER, GH_TOKEN, GITHUB_REPOSITORY +// Outputs: head_ref, head_sha, cross_repo, pr_state + +import { execFileSync } from "node:child_process"; +import { setOutput } from "../output.js"; +import { fetchPrMeta } from "../github.js"; + +const prNumber = Number(process.env.PR_NUMBER || "0"); +const token = process.env.GH_TOKEN || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); + +if (!prNumber) { + console.error("Missing PR_NUMBER"); + process.exitCode = 2; +} else { + const meta = fetchPrMeta(prNumber); + let headSha = meta.headOid; + + if (!meta.isCrossRepository && meta.state === "OPEN") { + const remoteUrl = `https://x-access-token:${token}@github.com/${repo}.git`; + execFileSync("git", ["fetch", remoteUrl, meta.headRef], { cwd, stdio: "pipe" }); + execFileSync("git", ["checkout", "-B", meta.headRef, "FETCH_HEAD"], { cwd, stdio: "pipe" }); + headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe" }) + .toString("utf8") + .trim(); + } + + setOutput("head_ref", meta.headRef); + setOutput("head_sha", headSha); + setOutput("cross_repo", String(meta.isCrossRepository)); + setOutput("pr_state", meta.state); +} diff --git a/.agent/src/cli/commit.ts b/.agent/src/cli/commit.ts new file mode 100644 index 0000000..f3c2c45 --- /dev/null +++ b/.agent/src/cli/commit.ts @@ -0,0 +1,39 @@ +// CLI: stage, commit, and push changes. +// Usage: node .agent/dist/cli/commit.js +// Env: COMMIT_CWD or GITHUB_WORKSPACE, COMMIT_MESSAGE, BRANCH, GH_TOKEN, GITHUB_REPOSITORY +// PUSH_REF (optional — push to HEAD: instead of branch) +// PUSH_LEASE_OID (optional — use --force-with-lease=:) +// SET_UPSTREAM (optional — set upstream tracking) +// Outputs: committed (true/false), branch + +import { configureBotIdentity, commitAndPush } from "../git.js"; +import { setOutput } from "../output.js"; + +const cwd = process.env.COMMIT_CWD || process.env.GITHUB_WORKSPACE || process.cwd(); +const message = process.env.COMMIT_MESSAGE || "chore: agent changes"; +const branch = process.env.BRANCH || ""; +const token = process.env.GH_TOKEN || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; +const pushRef = process.env.PUSH_REF || undefined; +const pushLeaseOid = process.env.PUSH_LEASE_OID || undefined; +const setUpstream = process.env.SET_UPSTREAM === "true"; + +configureBotIdentity(cwd); + +const result = commitAndPush({ + message, + branch, + token, + repo, + cwd, + pushRef, + pushLeaseOid, + setUpstream, +}); + +setOutput("committed", String(result.committed)); +setOutput("branch", result.branch); + +if (!result.committed) { + console.log("No changes to commit."); +} diff --git a/.agent/src/cli/create-discussion.ts b/.agent/src/cli/create-discussion.ts new file mode 100644 index 0000000..7212d54 --- /dev/null +++ b/.agent/src/cli/create-discussion.ts @@ -0,0 +1,58 @@ +#!/usr/bin/env node +// CLI: create a GitHub Discussion from a markdown body file. +// Env: GITHUB_REPOSITORY, DISCUSSION_CATEGORY, DISCUSSION_TITLE, BODY_FILE, +// DISCUSSION_FOOTER (optional) + +import { existsSync, readFileSync } from "node:fs"; +import { createRepositoryDiscussion } from "../discussion.js"; +import { setOutput } from "../output.js"; + +function requiredEnv(name: string): string { + const value = process.env[name]?.trim() || ""; + if (!value) throw new Error(`${name} is required`); + return value; +} + +function parseRepoSlug(slug: string): { owner: string; repo: string } { + const [owner, repo, extra] = slug.split("/"); + if (!owner || !repo || extra) { + throw new Error(`GITHUB_REPOSITORY must be owner/repo (got: ${slug || "missing"})`); + } + return { owner, repo }; +} + +function main(): number { + try { + const { owner, repo } = parseRepoSlug(requiredEnv("GITHUB_REPOSITORY")); + const category = requiredEnv("DISCUSSION_CATEGORY"); + const title = requiredEnv("DISCUSSION_TITLE"); + const bodyFile = requiredEnv("BODY_FILE"); + const footer = process.env.DISCUSSION_FOOTER?.trim() || ""; + + if (!existsSync(bodyFile)) { + throw new Error(`Discussion body file was not produced: ${bodyFile}`); + } + + const body = readFileSync(bodyFile, "utf8").trim(); + if (!body) { + throw new Error("Discussion body is empty"); + } + + const discussion = createRepositoryDiscussion( + owner, + repo, + category, + title, + footer ? `${body}\n\n---\n${footer}` : body, + ); + + setOutput("discussion_url", discussion.url); + console.log(`Discussion created: ${discussion.url}`); + return 0; + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } +} + +process.exitCode = main(); diff --git a/.agent/src/cli/create-issue.ts b/.agent/src/cli/create-issue.ts new file mode 100644 index 0000000..fa05238 --- /dev/null +++ b/.agent/src/cli/create-issue.ts @@ -0,0 +1,49 @@ +// CLI: create a GitHub issue, optionally with an origin-link footer. +// Usage: node .agent/dist/cli/create-issue.js +// Env: ISSUE_TITLE, ISSUE_BODY, SOURCE_KIND (optional), TARGET_URL (optional) +// Outputs: issue_number, issue_url +// +// When SOURCE_KIND and TARGET_URL are set, appends a footer pointing back +// to the origin (e.g. "Requested via issue_comment at "). Callers +// without an origin can omit those env vars. + +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { randomBytes } from "node:crypto"; +import { createIssue } from "../github.js"; +import { setOutput } from "../output.js"; + +const MAX_TITLE_LENGTH = 70; + +function normalizeTitle(raw: string): string { + const collapsed = raw.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim(); + if (!collapsed) { + return "Agent-created issue"; + } + if (collapsed.length > MAX_TITLE_LENGTH) { + return `${collapsed.slice(0, MAX_TITLE_LENGTH - 3)}...`; + } + return collapsed; +} + +const title = normalizeTitle(process.env.ISSUE_TITLE || ""); +const rawBody = process.env.ISSUE_BODY || ""; +const sourceKind = process.env.SOURCE_KIND || ""; +const targetUrl = process.env.TARGET_URL || ""; + +const bodyLines: string[] = [rawBody]; +if (targetUrl) { + bodyLines.push("", "---", "", `Requested via ${sourceKind || "mention"} at ${targetUrl}`); +} + +const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; +const bodyFile = join(runnerTemp, `agent-issue-body-${randomBytes(8).toString("hex")}.md`); +writeFileSync(bodyFile, bodyLines.join("\n") + "\n", "utf8"); + +const issueUrl = createIssue({ title, bodyFile }); +const numberMatch = issueUrl.match(/(\d+)$/); +const issueNumber = numberMatch ? numberMatch[1] : ""; + +setOutput("issue_url", issueUrl); +setOutput("issue_number", issueNumber); +console.log(`Issue created: ${issueUrl}`); diff --git a/.agent/src/cli/create-pr.ts b/.agent/src/cli/create-pr.ts new file mode 100644 index 0000000..1a20b00 --- /dev/null +++ b/.agent/src/cli/create-pr.ts @@ -0,0 +1,54 @@ +// CLI: create a draft PR if one doesn't already exist for the branch. +// Usage: node .agent/dist/cli/create-pr.js +// Env: BRANCH, BASE_BRANCH, PR_TITLE, PR_BODY, ISSUE_NUMBER, REQUESTED_BY +// Outputs: pr_url, pr_number + +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { randomBytes } from "node:crypto"; +import { findExistingPr, createPr } from "../github.js"; +import { setOutput } from "../output.js"; + +const branch = process.env.BRANCH || ""; +const baseBranch = process.env.BASE_BRANCH || "main"; +const issueNumber = process.env.ISSUE_NUMBER || ""; +const requestedBy = process.env.REQUESTED_BY || ""; + +function parsePrNumber(prUrl: string): string { + const match = prUrl.match(/\/pull\/(\d+)(?:[/?#].*)?$/); + return match ? match[1] : ""; +} + +// Check for existing PR first +const existing = findExistingPr(branch); +if (existing) { + setOutput("pr_url", existing); + setOutput("pr_number", parsePrNumber(existing)); + console.log(`Existing PR found: ${existing}`); + process.exit(0); +} + +// Build title and body +const title = process.env.PR_TITLE || `feat: implement #${issueNumber}`; +const body = process.env.PR_BODY || [ + `Implements #${issueNumber}.`, + "", + requestedBy ? `Requested by @${requestedBy}.` : "", + "Generated by the `agent-implement` workflow using Codex.", +].filter(Boolean).join("\n"); + +const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; +const bodyFile = join(runnerTemp, `pr-body-${randomBytes(8).toString("hex")}.md`); +writeFileSync(bodyFile, body + "\n", "utf8"); + +const prUrl = createPr({ + base: baseBranch, + head: branch, + title, + bodyFile, + draft: true, +}); + +setOutput("pr_url", prUrl); +setOutput("pr_number", parsePrNumber(prUrl)); +console.log(`PR created: ${prUrl}`); diff --git a/.agent/src/cli/detect-head-change.ts b/.agent/src/cli/detect-head-change.ts new file mode 100644 index 0000000..601d0c9 --- /dev/null +++ b/.agent/src/cli/detect-head-change.ts @@ -0,0 +1,18 @@ +// CLI: detect whether the checked-out branch HEAD changed during a run. +// Usage: node .agent/dist/cli/detect-head-change.js +// Env: ORIGINAL_HEAD_SHA, GITHUB_WORKSPACE +// Outputs: head_changed, current_head + +import { currentHead, hasHeadChanged } from "../git.js"; +import { setOutput } from "../output.js"; + +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const originalHead = process.env.ORIGINAL_HEAD_SHA || ""; +const current = currentHead(cwd); + +if (!originalHead) { + console.warn("ORIGINAL_HEAD_SHA was not set; treating branch head as unchanged."); +} + +setOutput("current_head", current); +setOutput("head_changed", String(hasHeadChanged(originalHead, cwd))); diff --git a/.agent/src/cli/dispatch-agent-implement.ts b/.agent/src/cli/dispatch-agent-implement.ts new file mode 100644 index 0000000..2702b14 --- /dev/null +++ b/.agent/src/cli/dispatch-agent-implement.ts @@ -0,0 +1,42 @@ +// CLI: dispatch agent-implement.yml with the standard input contract. +// Usage: node .agent/dist/cli/dispatch-agent-implement.js +// Env: GITHUB_REPOSITORY, DEFAULT_BRANCH, ISSUE_NUMBER, REQUESTED_BY, +// REQUEST_TEXT, APPROVAL_COMMENT_URL, SESSION_FORK_FROM_THREAD_KEY, +// BASE_BRANCH, BASE_PR, IMPLEMENTATION_ROUTE, IMPLEMENTATION_PROMPT, +// AUTOMATION_MODE, AUTOMATION_MAX_ROUNDS + +import { dispatchWorkflow } from "../github.js"; + +const repo = process.env.GITHUB_REPOSITORY || ""; +const ref = process.env.DEFAULT_BRANCH || ""; +const issueNumber = process.env.ISSUE_NUMBER || ""; +const requestedBy = process.env.REQUESTED_BY || ""; +const requestText = process.env.REQUEST_TEXT || ""; +const approvalCommentUrl = process.env.APPROVAL_COMMENT_URL || ""; +const sessionForkFromThreadKey = process.env.SESSION_FORK_FROM_THREAD_KEY || ""; +const baseBranch = process.env.BASE_BRANCH || ""; +const basePr = process.env.BASE_PR || ""; +const implementationRoute = process.env.IMPLEMENTATION_ROUTE || "implement"; +const implementationPrompt = process.env.IMPLEMENTATION_PROMPT || implementationRoute; +const automationMode = process.env.AUTOMATION_MODE || "disabled"; +const automationMaxRounds = process.env.AUTOMATION_MAX_ROUNDS || "12"; + +if (!repo || !ref || !issueNumber) { + console.error("Missing required env: GITHUB_REPOSITORY, DEFAULT_BRANCH, ISSUE_NUMBER"); + process.exitCode = 2; +} else { + dispatchWorkflow(repo, "agent-implement.yml", ref, { + issue_number: issueNumber, + requested_by: requestedBy, + approval_comment_url: approvalCommentUrl, + request_text: requestText, + session_fork_from_thread_key: sessionForkFromThreadKey, + base_branch: baseBranch, + base_pr: basePr, + implementation_route: implementationRoute, + implementation_prompt: implementationPrompt, + automation_mode: automationMode, + automation_max_rounds: automationMaxRounds, + }); + console.log(`Dispatched agent-implement.yml for ${implementationRoute} issue #${issueNumber}`); +} diff --git a/.agent/src/cli/dispatch-agent-orchestrator.ts b/.agent/src/cli/dispatch-agent-orchestrator.ts new file mode 100644 index 0000000..2ed93a5 --- /dev/null +++ b/.agent/src/cli/dispatch-agent-orchestrator.ts @@ -0,0 +1,94 @@ +// CLI: dispatch agent-orchestrator.yml with a post-action handoff envelope. +// Env: GITHUB_REPOSITORY, DEFAULT_BRANCH, AUTOMATION_MODE, SOURCE_ACTION, +// SOURCE_CONCLUSION, RESPONSE_FILE, TARGET_NUMBER, NEXT_TARGET_NUMBER, +// REQUESTED_BY, REQUEST_TEXT, AUTOMATION_CURRENT_ROUND, +// AUTOMATION_MAX_ROUNDS, SESSION_BUNDLE_MODE, SOURCE_RUN_ID, TARGET_KIND, +// AUTHOR_ASSOCIATION, ACCESS_POLICY, REPOSITORY_PRIVATE, ORCHESTRATION_ENABLED, +// SOURCE_RECOMMENDED_NEXT_STEP, SOURCE_HANDOFF_CONTEXT, BASE_BRANCH, BASE_PR + +import { readFileSync } from "node:fs"; +import { dispatchWorkflow } from "../github.js"; +import { + automationModeAllowsHandoff, + buildReviewFixPrHandoffContext, + extractReviewConclusion, + extractReviewRecommendedNextStep, + normalizeConclusion, + normalizeRecommendedNextStep, +} from "../handoff.js"; + +function readResponseFile(): string { + const responseFile = process.env.RESPONSE_FILE || ""; + if (!responseFile) return ""; + try { + return readFileSync(responseFile, "utf8"); + } catch { + return ""; + } +} + +function sourceReviewNeedsFixPr(sourceAction: string, sourceConclusion: string, recommendedNextStep: string): boolean { + if (sourceAction.trim().toLowerCase() !== "review") return false; + if (normalizeRecommendedNextStep(recommendedNextStep) === "human_decision") return false; + return new Set(["minor_issues", "needs_rework", "changes_requested"]).has(normalizeConclusion(sourceConclusion)); +} + +function sourceReviewRecommendedNextStep(sourceAction: string, rawResponse: string): string { + if (sourceAction.trim().toLowerCase() !== "review") return ""; + return extractReviewRecommendedNextStep(rawResponse); +} + +const automationMode = process.env.AUTOMATION_MODE || "disabled"; +const sourceAction = process.env.SOURCE_ACTION || ""; +const isManualOrchestrateStart = sourceAction.trim().toLowerCase() === "orchestrate"; +const orchestrationEnabled = String(process.env.ORCHESTRATION_ENABLED || "").trim().toLowerCase() === "true"; +if (!isManualOrchestrateStart && !orchestrationEnabled && !automationModeAllowsHandoff(automationMode)) { + console.log("Skipping orchestrator dispatch: automation mode is disabled"); + process.exit(0); +} +const effectiveAutomationMode = orchestrationEnabled && !automationModeAllowsHandoff(automationMode) + ? "heuristics" + : automationMode; + +const repo = process.env.GITHUB_REPOSITORY || ""; +const ref = process.env.DEFAULT_BRANCH || ""; +const rawResponse = readResponseFile(); +const sourceConclusion = process.env.SOURCE_CONCLUSION || extractReviewConclusion(rawResponse) || "unknown"; +const sourceRecommendedNextStep = normalizeRecommendedNextStep( + process.env.SOURCE_RECOMMENDED_NEXT_STEP || sourceReviewRecommendedNextStep(sourceAction, rawResponse), +); +const sourceHandoffContext = process.env.SOURCE_HANDOFF_CONTEXT || + (sourceReviewNeedsFixPr(sourceAction, sourceConclusion, sourceRecommendedNextStep) + ? buildReviewFixPrHandoffContext(rawResponse) + : ""); +const targetNumber = process.env.TARGET_NUMBER || ""; +const targetKind = process.env.TARGET_KIND || ""; + +if (!repo || !ref || !sourceAction || !targetNumber) { + console.error("Missing required env: GITHUB_REPOSITORY, DEFAULT_BRANCH, SOURCE_ACTION, TARGET_NUMBER"); + process.exit(2); +} + +dispatchWorkflow(repo, "agent-orchestrator.yml", ref, { + automation_mode: effectiveAutomationMode, + automation_current_round: process.env.AUTOMATION_CURRENT_ROUND || "1", + automation_max_rounds: process.env.AUTOMATION_MAX_ROUNDS || "12", + source_action: sourceAction, + source_conclusion: sourceConclusion, + source_recommended_next_step: sourceRecommendedNextStep, + source_run_id: process.env.SOURCE_RUN_ID || process.env.GITHUB_RUN_ID || "", + target_kind: targetKind, + target_number: targetNumber, + author_association: process.env.AUTHOR_ASSOCIATION || "", + access_policy: process.env.ACCESS_POLICY || "", + repository_private: process.env.REPOSITORY_PRIVATE || "", + next_target_number: process.env.NEXT_TARGET_NUMBER || "", + source_handoff_context: sourceHandoffContext, + requested_by: process.env.REQUESTED_BY || "", + request_text: process.env.REQUEST_TEXT || "", + session_bundle_mode: process.env.SESSION_BUNDLE_MODE || "", + base_branch: process.env.BASE_BRANCH || "", + base_pr: process.env.BASE_PR || "", +}); + +console.log(`Dispatched agent-orchestrator.yml after ${sourceAction} for #${targetNumber}`); diff --git a/.agent/src/cli/extract-context.ts b/.agent/src/cli/extract-context.ts new file mode 100644 index 0000000..c29fe8b --- /dev/null +++ b/.agent/src/cli/extract-context.ts @@ -0,0 +1,246 @@ +// CLI: extract portal event context from GitHub webhook payload. +// Usage: node .agent/dist/cli/extract-context.js +// Env: GITHUB_EVENT_PATH, GITHUB_EVENT_NAME, GITHUB_REPOSITORY, INPUT_MENTION, +// INPUT_TRIGGER_KIND, INPUT_LABEL_NAME, INPUT_AUTHOR_ASSOCIATION +// Outputs: should_respond, association, body, source_kind, target_kind, +// target_number, target_url, reaction_subject_id, response_kind, +// source_comment_id, source_comment_url, review_comment_id, +// discussion_node_id, reply_to_id, requested_by, requested_route, requested_skill + +import { readFileSync } from "node:fs"; +import { isKnownAuthorAssociation } from "../access-policy.js"; +import { ghApi, ghApiOk } from "../github.js"; +import { setOutput } from "../output.js"; +import { + DEFAULT_MENTION, + extractEventContext, + getAuthorAssociation, + getRequestedBy, + shouldSkipSender, + shouldRespondToMention, +} from "../context.js"; +import { isApprovalCommand } from "../approval.js"; +import { resolveDiscussionReplyTo } from "../discussion.js"; +import { extractRequestedRouteDecision, resolveRequestedLabel } from "../triage.js"; + +const eventPath = process.env.GITHUB_EVENT_PATH; +const eventName = process.env.GITHUB_EVENT_NAME || ""; +const mention = process.env.INPUT_MENTION || DEFAULT_MENTION; +const triggerKind = String(process.env.INPUT_TRIGGER_KIND || "mention").trim().toLowerCase(); +const labelName = process.env.INPUT_LABEL_NAME || ""; +const authorAssociationOverride = process.env.INPUT_AUTHOR_ASSOCIATION || ""; +const repository = process.env.GITHUB_REPOSITORY || ""; +const ASSOCIATIONS_TRUSTED_WITHOUT_REFRESH = new Set([ + "OWNER", + "MEMBER", + "COLLABORATOR", +]); +const WEAK_ASSOCIATIONS_FOR_COLLABORATOR_FALLBACK = new Set([ + "CONTRIBUTOR", + "FIRST_TIME_CONTRIBUTOR", + "FIRST_TIMER", + "NONE", +]); + +function normalizeAssociation(association: string): string { + return String(association || "").trim().toUpperCase(); +} + +function hasOrgMembership(orgLogin: string, userLogin: string): boolean { + const membershipState = ghApi([ + `orgs/${orgLogin}/memberships/${userLogin}`, + "--jq", + ".state // empty", + ]).toLowerCase(); + if (membershipState === "active") { + return true; + } + + // Public membership endpoint returns 204 (empty body) on success, so use + // ghApiOk rather than checking the body. + return ghApiOk([`orgs/${orgLogin}/members/${userLogin}`]); +} + +function hasRepositoryPermission(userLogin: string): boolean { + if (!repository || !userLogin) { + return false; + } + + const permission = ghApi([ + `repos/${repository}/collaborators/${userLogin}/permission`, + "--jq", + ".permission // .role_name // empty", + ]).toLowerCase(); + + return Boolean(permission) && permission !== "none"; +} + +function hasRepositoryCollaborator(userLogin: string): boolean { + const login = String(userLogin || "").trim(); + if (!repository || !login) { + return false; + } + + return ghApiOk([`repos/${repository}/collaborators/${login}`]); +} + +// eslint-disable-next-line @typescript-eslint/no-explicit-any +function resolveLabelActorAssociation(payload: Record): string { + const override = String(authorAssociationOverride || "").trim().toUpperCase(); + if (override) { + return override; + } + + const senderLogin = String(payload.sender?.login || "").trim(); + const ownerLogin = String(payload.repository?.owner?.login || repository.split("/")[0] || "").trim(); + const ownerType = String(payload.repository?.owner?.type || "").trim().toLowerCase(); + if (!senderLogin) { + return "NONE"; + } + + if (ownerType === "user" && senderLogin.toLowerCase() === ownerLogin.toLowerCase()) { + return "OWNER"; + } + + if (ownerType === "organization" && ownerLogin && hasOrgMembership(ownerLogin, senderLogin)) { + return "MEMBER"; + } + + if (hasRepositoryPermission(senderLogin)) { + return "COLLABORATOR"; + } + + return "NONE"; +} + +function refreshIssueAssociation( + association: string, + issueNumber: string, +): string { + if ( + eventName !== "issues" || + !repository || + !issueNumber + ) { + return normalizeAssociation(association) || association; + } + + const refreshed = ghApi([ + `repos/${repository}/issues/${issueNumber}`, + "--jq", + ".author_association // empty", + ]).toUpperCase(); + return refreshed || normalizeAssociation(association) || association; +} + +// eslint-disable-next-line @typescript-eslint/no-explicit-any +function normalizeMentionAuthorAssociation(association: string, payload: Record): string { + const normalized = normalizeAssociation(association); + if (authorAssociationOverride || ASSOCIATIONS_TRUSTED_WITHOUT_REFRESH.has(normalized)) { + return normalized || association; + } + + const resolved = refreshIssueAssociation( + normalized || association, + String(payload.issue?.number || ""), + ); + const resolvedNormalized = normalizeAssociation(resolved); + if (ASSOCIATIONS_TRUSTED_WITHOUT_REFRESH.has(resolvedNormalized)) { + return resolvedNormalized; + } + + if ( + WEAK_ASSOCIATIONS_FOR_COLLABORATOR_FALLBACK.has(resolvedNormalized) && + hasRepositoryCollaborator(getRequestedBy(eventName, payload)) + ) { + return "COLLABORATOR"; + } + + return resolvedNormalized || resolved; +} + +if (!eventPath || !eventName) { + console.error("Missing GITHUB_EVENT_PATH or GITHUB_EVENT_NAME"); + process.exitCode = 2; +} else { + const payload = JSON.parse(readFileSync(eventPath, "utf8")); + + // Gate 1: skip bot-authored events + if (shouldSkipSender(payload)) { + setOutput("should_respond", "false"); + console.log("Skipping bot-authored event"); + } else { + // Gate 2: check author association + const association = triggerKind === "label" + ? resolveLabelActorAssociation(payload) + : normalizeMentionAuthorAssociation( + authorAssociationOverride || getAuthorAssociation(eventName, payload), + payload, + ); + if (!isKnownAuthorAssociation(association)) { + setOutput("should_respond", "false"); + console.log(`Skipping unsupported sender association: ${association}`); + } else { + const ctx = extractEventContext(eventName, payload); + + // Gate 3: validate target number + if (!ctx.targetNumber) { + setOutput("should_respond", "false"); + console.log("No target number found"); + } + // Gate 4: check for live mention when mention-triggered + else if (triggerKind !== "label" && !shouldRespondToMention(eventName, payload, mention)) { + setOutput("should_respond", "false"); + console.log("No live mention found"); + } + // Gate 5: skip approval commands on mention triggers + else if (triggerKind !== "label" && isApprovalCommand(ctx.body, mention)) { + setOutput("should_respond", "false"); + console.log("Skipping approval command (handled by agent-approve)"); + } else { + // Resolve discussion reply threading if needed + let replyToId = ""; + if (ctx.discussionCommentNodeId) { + try { + replyToId = resolveDiscussionReplyTo(ctx.discussionCommentNodeId); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.warn(`Could not resolve discussion reply-to: ${msg}`); + } + } + + const requestedBy = + (triggerKind === "label" ? payload.sender?.login : "") || getRequestedBy(eventName, payload); + const requestedLabel = triggerKind === "label" ? resolveRequestedLabel(labelName) : null; + const requestedMention = triggerKind === "label" + ? { route: "", skill: "" } + : extractRequestedRouteDecision(ctx.body, mention); + const requestedRoute = requestedLabel?.route || requestedMention.route; + const requestedSkill = requestedLabel?.skill || requestedMention.skill; + + if (triggerKind === "label" && !requestedLabel) { + setOutput("should_respond", "false"); + console.log(`Ignoring unsupported agent label: ${labelName || "missing"}`); + } else { + setOutput("should_respond", "true"); + setOutput("association", association); + setOutput("body", ctx.body); + setOutput("source_kind", ctx.sourceKind); + setOutput("target_kind", ctx.targetKind); + setOutput("target_number", ctx.targetNumber); + setOutput("target_url", ctx.targetUrl); + setOutput("reaction_subject_id", ctx.reactionSubjectId); + setOutput("response_kind", ctx.responseKind); + setOutput("source_comment_id", ctx.sourceCommentId || ""); + setOutput("source_comment_url", ctx.sourceCommentUrl || ""); + setOutput("review_comment_id", ctx.reviewCommentId || ""); + setOutput("discussion_node_id", ctx.discussionNodeId || ""); + setOutput("reply_to_id", replyToId); + setOutput("requested_by", requestedBy); + setOutput("requested_route", requestedRoute); + setOutput("requested_skill", requestedSkill); + } + } + } + } +} diff --git a/.agent/src/cli/fetch-discussion-transcript.ts b/.agent/src/cli/fetch-discussion-transcript.ts new file mode 100644 index 0000000..9281acf --- /dev/null +++ b/.agent/src/cli/fetch-discussion-transcript.ts @@ -0,0 +1,125 @@ +#!/usr/bin/env node + +// CLI: fetch a discussion transcript via GitHub GraphQL. +// Usage: node .agent/dist/cli/fetch-discussion-transcript.js +// Env: REPO_SLUG (optional, falls back to `gh repo view`) + +import { execFileSync } from "node:child_process"; + +import { + buildDiscussionTranscript, + fetchDiscussionTranscript, +} from "../discussion-transcript.js"; +import { createGhGraphqlClient, type GraphQLClient } from "../github-graphql.js"; + +const MAX_BUFFER = 16 * 1024 * 1024; +const USAGE = "Usage: fetch-discussion-transcript.js \n"; +const REPO_ERROR = + "Could not determine repository. Set REPO_SLUG or run from a git checkout.\n"; + +type ExecGh = ( + file: string, + args: readonly string[], + options: { stdio: ["pipe", "pipe", "pipe"]; maxBuffer: number }, +) => string | Buffer; + +interface WritableLike { + write(chunk: string): void; +} + +/** + * Resolves the current repository slug from the environment or `gh repo view`. + */ +export function resolveRepoSlug( + options: { + env?: NodeJS.ProcessEnv; + execGh?: ExecGh; + } = {}, +): string { + const env = options.env || process.env; + const execGh = options.execGh || execFileSync; + const repoSlug = env.REPO_SLUG || ""; + if (repoSlug) { + return repoSlug; + } + + return execGh( + "gh", + ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], + { + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: MAX_BUFFER, + }, + ) + .toString("utf8") + .trim(); +} + +/** + * Parses the discussion number argument. + */ +export function parseDiscussionNumber(value: string | undefined): number | null { + const number = Number(value); + if (!Number.isInteger(number) || number <= 0) { + return null; + } + return number; +} + +export function runFetchDiscussionTranscriptCli( + argv: string[], + options: { + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + resolveRepoSlug?: (options?: { + env?: NodeJS.ProcessEnv; + execGh?: ExecGh; + }) => string; + createClient?: () => GraphQLClient; + fetchDiscussionTranscript?: typeof fetchDiscussionTranscript; + buildDiscussionTranscript?: typeof buildDiscussionTranscript; + } = {}, +): number { + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + const number = parseDiscussionNumber(argv[0]); + if (!number) { + stderr.write(USAGE); + return 1; + } + + const resolveRepo = options.resolveRepoSlug || resolveRepoSlug; + const repoSlug = resolveRepo({ env }); + const [owner, repo] = repoSlug.split("/", 2); + if (!owner || !repo) { + stderr.write(REPO_ERROR); + return 1; + } + + const createClient = options.createClient || createGhGraphqlClient; + const fetchTranscript = + options.fetchDiscussionTranscript || fetchDiscussionTranscript; + const renderTranscript = + options.buildDiscussionTranscript || buildDiscussionTranscript; + + try { + const { discussionMeta, comments } = fetchTranscript( + createClient(), + owner, + repo, + number, + ); + stdout.write(renderTranscript(discussionMeta, comments)); + return 0; + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runFetchDiscussionTranscriptCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/bootstrap-branch.ts b/.agent/src/cli/memory/bootstrap-branch.ts new file mode 100644 index 0000000..65b173f --- /dev/null +++ b/.agent/src/cli/memory/bootstrap-branch.ts @@ -0,0 +1,223 @@ +#!/usr/bin/env node +// CLI: initialize a local agent/memory branch inside the current git repo. +// Usage: node .agent/dist/cli/memory/bootstrap-branch.js [--repo ] [--branch ] [--remote ] +// Env: REPO_SLUG, GITHUB_REPOSITORY + +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { parseArgs, type ParseArgsConfig } from "node:util"; + +import { ensureMemoryStructure } from "../../memory-artifacts.js"; +import { + commit, + configureBotIdentity, + git, + hasStagedChanges, + stageAll, +} from "../../git.js"; + +const DEFAULT_BRANCH = "agent/memory"; +const DEFAULT_REMOTE = "origin"; + +const USAGE = [ + "Usage: memory/bootstrap-branch.js [--repo ] [--branch ] [--remote ]", + "", + "Options:", + ` --repo Repository slug used in seeded stubs (defaults to REPO_SLUG, GITHUB_REPOSITORY, or ${DEFAULT_REMOTE} remote URL)`, + ` --branch Memory branch to create or update (default: ${DEFAULT_BRANCH})`, + ` --remote Remote used for repo-slug inference and next-step hints (default: ${DEFAULT_REMOTE})`, + " -h, --help Show this message", + "", + "This command creates or updates a local memory branch and seeds PROJECT.md / MEMORY.md", + "without changing your current checkout. Push it separately when ready.", + "", +].join("\n"); + +interface WritableLike { write(chunk: string): void; } + +interface ParsedBootstrapArgs { + repo: string; + branch: string; + remote: string; + help: boolean; +} + +const ARG_CONFIG = { + options: { + repo: { type: "string" }, + branch: { type: "string" }, + remote: { type: "string" }, + help: { type: "boolean", short: "h", default: false }, + }, + allowPositionals: false, + strict: true, +} as const satisfies ParseArgsConfig; + +export function parseGitHubRepoSlugFromRemoteUrl(url: string): string { + const match = url.trim().match(/github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?$/i); + return match?.[1] || ""; +} + +function hasLocalBranch(branch: string, repoRoot: string): boolean { + try { + git(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repoRoot); + return true; + } catch { + return false; + } +} + +function hasRemoteTrackingBranch(branch: string, remote: string, repoRoot: string): boolean { + try { + git(["show-ref", "--verify", "--quiet", `refs/remotes/${remote}/${branch}`], repoRoot); + return true; + } catch { + return false; + } +} + +function currentBranch(repoRoot: string): string { + try { + return git(["branch", "--show-current"], repoRoot); + } catch { + return ""; + } +} + +function inferRepoSlug(repoRoot: string, remote: string): string { + try { + return parseGitHubRepoSlugFromRemoteUrl(git(["remote", "get-url", remote], repoRoot)); + } catch { + return ""; + } +} + +export function parseMemoryBootstrapBranchArgs( + argv: string[], + env: NodeJS.ProcessEnv = process.env, + cwd: string = process.cwd(), +): ParsedBootstrapArgs { + const { values } = parseArgs({ ...ARG_CONFIG, args: argv }); + const remote = (values.remote as string | undefined) || DEFAULT_REMOTE; + const repoRoot = git(["rev-parse", "--show-toplevel"], cwd); + + return { + repo: (values.repo as string | undefined) + || env.REPO_SLUG + || env.GITHUB_REPOSITORY + || inferRepoSlug(repoRoot, remote), + branch: (values.branch as string | undefined) || DEFAULT_BRANCH, + remote, + help: Boolean(values.help), + }; +} + +export function runMemoryBootstrapBranchCli( + argv: string[], + options: { + cwd?: string; + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + } = {}, +): number { + const cwd = options.cwd || process.cwd(); + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + + let args: ParsedBootstrapArgs; + let repoRoot = ""; + try { + repoRoot = git(["rev-parse", "--show-toplevel"], cwd); + args = parseMemoryBootstrapBranchArgs(argv, env, cwd); + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n\n${USAGE}`); + return 1; + } + + if (args.help) { + stdout.write(USAGE); + return 0; + } + + if (!args.repo || !args.repo.includes("/")) { + stderr.write( + `Missing or invalid repository slug (got: ${args.repo || "empty"}).\n` + + `Pass --repo or configure a GitHub origin remote.\n\n${USAGE}`, + ); + return 1; + } + + const worktreeDir = mkdtempSync(join(tmpdir(), "agent-memory-bootstrap-")); + let addedWorktree = false; + + try { + const branchExists = hasLocalBranch(args.branch, repoRoot); + const remoteBranchExists = !branchExists && hasRemoteTrackingBranch(args.branch, args.remote, repoRoot); + const checkedOutBranch = currentBranch(repoRoot); + + if (branchExists && checkedOutBranch === args.branch) { + stderr.write( + `Branch ${args.branch} is already checked out in the current worktree.\n` + + "Switch to another branch before rerunning bootstrap.\n", + ); + return 1; + } + + git(["worktree", "add", "--detach", worktreeDir, "HEAD"], repoRoot); + addedWorktree = true; + + if (branchExists) { + git(["checkout", args.branch], worktreeDir); + } else if (remoteBranchExists) { + git(["checkout", "-b", args.branch, `${args.remote}/${args.branch}`], worktreeDir); + } else { + git(["checkout", "--orphan", args.branch], worktreeDir); + try { git(["rm", "-rf", "."], worktreeDir); } catch { /* ok */ } + try { git(["clean", "-fdx"], worktreeDir); } catch { /* ok */ } + } + + const initResult = ensureMemoryStructure(worktreeDir, args.repo); + configureBotIdentity(worktreeDir); + stageAll(worktreeDir); + + let committed = false; + if (hasStagedChanges(worktreeDir)) { + commit("chore(memory): initialize memory branch", worktreeDir); + committed = true; + } + + stdout.write( + `${JSON.stringify( + { + repoRoot, + repo: args.repo, + branch: args.branch, + remote: args.remote, + createdBranch: !branchExists, + committed, + createdFiles: initResult.createdFiles.map((file) => file.replace(`${worktreeDir}/`, "")), + nextStep: `git push ${args.remote} ${args.branch}`, + }, + null, + 2, + )}\n`, + ); + return 0; + } catch (error: unknown) { + stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); + return 1; + } finally { + if (addedWorktree) { + try { git(["worktree", "remove", "--force", worktreeDir], repoRoot); } catch { /* ok */ } + } + try { rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* ok */ } + } +} + +if (require.main === module) { + process.exitCode = runMemoryBootstrapBranchCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/init.ts b/.agent/src/cli/memory/init.ts new file mode 100644 index 0000000..e85e4ef --- /dev/null +++ b/.agent/src/cli/memory/init.ts @@ -0,0 +1,101 @@ +#!/usr/bin/env node +// CLI: initialize the agent memory tree in a local directory. +// Usage: node .agent/dist/cli/memory/init.js [--dir ] [--repo ] +// Env: MEMORY_DIR, REPO_SLUG, GITHUB_REPOSITORY + +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; + +import { ensureMemoryStructure } from "../../memory-artifacts.js"; + +const USAGE = [ + "Usage: memory/init.js [--dir ] [--repo ]", + "", + "Options:", + " --dir Memory directory to initialize (defaults to MEMORY_DIR or cwd)", + " --repo Repository slug used in seeded stubs (defaults to REPO_SLUG or GITHUB_REPOSITORY)", + " -h, --help Show this message", + "", +].join("\n"); + +interface WritableLike { write(chunk: string): void; } + +export interface ParsedMemoryInitArgs { + dir: string; + repo: string; + help: boolean; +} + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + repo: { type: "string" }, + help: { type: "boolean", short: "h", default: false }, + }, + allowPositionals: false, + strict: true, +} as const satisfies ParseArgsConfig; + +export function parseMemoryInitArgs( + argv: string[], + env: NodeJS.ProcessEnv = process.env, +): ParsedMemoryInitArgs { + const { values } = parseArgs({ ...ARG_CONFIG, args: argv }); + + return { + dir: (values.dir as string | undefined) || env.MEMORY_DIR || process.cwd(), + repo: (values.repo as string | undefined) || env.REPO_SLUG || env.GITHUB_REPOSITORY || "", + help: Boolean(values.help), + }; +} + +export function runMemoryInitCli( + argv: string[], + options: { + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + } = {}, +): number { + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + + let args: ParsedMemoryInitArgs; + try { + args = parseMemoryInitArgs(argv, env); + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n\n${USAGE}`); + return 1; + } + + if (args.help) { + stdout.write(USAGE); + return 0; + } + + if (!args.repo || !args.repo.includes("/")) { + stderr.write(`Missing or invalid repository slug (got: ${args.repo || "empty"}).\n\n${USAGE}`); + return 1; + } + + const rootDir = resolve(args.dir); + const result = ensureMemoryStructure(rootDir, args.repo); + stdout.write( + `${JSON.stringify( + { + repo: args.repo, + memoryDir: rootDir, + createdFiles: result.createdFiles, + }, + null, + 2, + )}\n`, + ); + return 0; +} + +if (require.main === module) { + process.exitCode = runMemoryInitCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/read-sync-state.ts b/.agent/src/cli/memory/read-sync-state.ts new file mode 100644 index 0000000..889bbaf --- /dev/null +++ b/.agent/src/cli/memory/read-sync-state.ts @@ -0,0 +1,26 @@ +#!/usr/bin/env node +// CLI: read the ref-backed memory sync state and emit cursors as step outputs. + +import { fetchMemorySyncState, memorySyncStateForRepo, type PushOptions } from "../../memory-sync-state.js"; +import { setOutput } from "../../output.js"; + +function buildOptions(): PushOptions { + const repo = process.env.GITHUB_REPOSITORY || process.env.REPO_SLUG || ""; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + return { repo, token: token || undefined }; +} + +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const repoSlug = process.env.REPO_SLUG || process.env.GITHUB_REPOSITORY || ""; +const fetched = fetchMemorySyncState(cwd, buildOptions()); +const state = repoSlug ? memorySyncStateForRepo(fetched, repoSlug) : fetched; + +setOutput("found", state ? "true" : "false"); +setOutput("last_sync_at", state?.last_sync_at || ""); +setOutput("issue_cursor", state?.cursors.issues || ""); +setOutput("pull_cursor", state?.cursors.pulls || ""); +setOutput("discussion_cursor", state?.cursors.discussions || ""); +setOutput("commit_cursor", state?.cursors.commits || ""); +setOutput("last_run_url", state?.last_run_url || ""); + +process.stdout.write(state ? `${JSON.stringify(state, null, 2)}\n` : "{}\n"); diff --git a/.agent/src/cli/memory/resolve-policy.ts b/.agent/src/cli/memory/resolve-policy.ts new file mode 100644 index 0000000..384b11c --- /dev/null +++ b/.agent/src/cli/memory/resolve-policy.ts @@ -0,0 +1,60 @@ +#!/usr/bin/env node +// CLI: resolve the memory mode for the current run-agent-task invocation. +// +// Env: +// ROUTE current route (e.g., answer, review) +// AGENT_MEMORY_POLICY raw JSON policy string (optional, falls back to default-enabled) +// MEMORY_MODE_OVERRIDE explicit mode ("enabled" | "read-only" | "disabled"), +// bypasses the policy entirely (used by dedicated memory +// workflows so they always have memory on) +// +// Outputs: +// mode resolved mode string +// read_enabled "true" | "false" +// write_enabled "true" | "false" + +import { setOutput } from "../../output.js"; +import { + DEFAULT_MEMORY_MODE, + type MemoryMode, + getMemoryModeForRoute, + isMemoryMode, + memoryModeAllowsRead, + memoryModeAllowsWrite, + parseMemoryPolicy, +} from "../../memory-policy.js"; + +export function resolveMode(): MemoryMode { + const override = String(process.env.MEMORY_MODE_OVERRIDE || "").trim().toLowerCase(); + if (override) { + if (!isMemoryMode(override)) { + console.error( + `Invalid MEMORY_MODE_OVERRIDE: ${override}. Expected enabled, read-only, or disabled.`, + ); + process.exitCode = 2; + return DEFAULT_MEMORY_MODE; + } + return override; + } + + const route = String(process.env.ROUTE || "").trim().toLowerCase(); + + try { + const policy = parseMemoryPolicy(process.env.AGENT_MEMORY_POLICY || ""); + return getMemoryModeForRoute(policy, route); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Invalid AGENT_MEMORY_POLICY: ${msg}. Falling back to disabled.`); + // Fall closed on a bad policy: disable memory for this run so a typo in + // the repo variable does not take down user-triggered routes. + return "disabled"; + } +} + +if (require.main === module) { + const mode = resolveMode(); + setOutput("mode", mode); + setOutput("read_enabled", memoryModeAllowsRead(mode) ? "true" : "false"); + setOutput("write_enabled", memoryModeAllowsWrite(mode) ? "true" : "false"); + process.stdout.write(`memory mode: ${mode}\n`); +} diff --git a/.agent/src/cli/memory/search.ts b/.agent/src/cli/memory/search.ts new file mode 100644 index 0000000..7366e3d --- /dev/null +++ b/.agent/src/cli/memory/search.ts @@ -0,0 +1,144 @@ +#!/usr/bin/env node +// CLI: search agent memory files in a local directory. +// Usage: node .agent/dist/cli/memory/search.js [--dir ] [--limit ] [--snippets ] [--json] +// Env: MEMORY_DIR (optional fallback for --dir) + +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; + +import { + formatMemorySearchResults, + searchMemory, + type MemorySearchResult, +} from "../../memory-search.js"; + +const USAGE = [ + "Usage: memory/search.js [--dir ] [--limit ] [--snippets ] [--json] ", + "", + "Options:", + " --dir Memory directory to search (defaults to MEMORY_DIR or cwd)", + " --limit Maximum number of files to return (default: 5)", + " --snippets Maximum snippets per file (default: 3)", + " --json Emit machine-readable JSON instead of text", + " -h, --help Show this message", + "", +].join("\n"); + +interface WritableLike { write(chunk: string): void; } + +export interface ParsedMemorySearchArgs { + query: string; + dir: string; + limit: number; + snippets: number; + json: boolean; + help: boolean; +} + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + limit: { type: "string" }, + snippets: { type: "string" }, + json: { type: "boolean", default: false }, + help: { type: "boolean", short: "h", default: false }, + }, + allowPositionals: true, + strict: true, +} as const satisfies ParseArgsConfig; + +function parsePositiveInteger(value: string, flagName: string): number { + const parsed = Number(value); + if (!Number.isInteger(parsed) || parsed <= 0) { + throw new Error(`${flagName} must be a positive integer`); + } + return parsed; +} + +export function parseMemorySearchArgs( + argv: string[], + env: NodeJS.ProcessEnv = process.env, +): ParsedMemorySearchArgs { + const { values, positionals } = parseArgs({ ...ARG_CONFIG, args: argv }); + + const dir = (values.dir as string | undefined) || env.MEMORY_DIR || ""; + const limit = values.limit !== undefined + ? parsePositiveInteger(values.limit as string, "--limit") + : 5; + const snippets = values.snippets !== undefined + ? parsePositiveInteger(values.snippets as string, "--snippets") + : 3; + + return { + query: positionals.join(" ").trim() || env.MEMORY_QUERY || "", + dir: dir || process.cwd(), + limit, + snippets, + json: Boolean(values.json), + help: Boolean(values.help), + }; +} + +function serializeJson(query: string, dir: string, results: MemorySearchResult[]): string { + return `${JSON.stringify( + { + query, + memoryDir: resolve(dir), + resultCount: results.length, + results, + }, + null, + 2, + )}\n`; +} + +export function runMemorySearchCli( + argv: string[], + options: { + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + } = {}, +): number { + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + + let args: ParsedMemorySearchArgs; + try { + args = parseMemorySearchArgs(argv, env); + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n\n${USAGE}`); + return 1; + } + + if (args.help) { stdout.write(USAGE); return 0; } + if (!args.query) { + stderr.write(`Missing search query.\n\n${USAGE}`); + return 1; + } + + try { + const results = searchMemory(args.query, { + rootDir: args.dir, + limit: args.limit, + snippetsPerFile: args.snippets, + }); + + if (args.json) { + stdout.write(serializeJson(args.query, args.dir, results)); + } else { + stdout.write(formatMemorySearchResults(args.query, results, args.dir)); + } + return 0; + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runMemorySearchCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/sync-github-artifacts.ts b/.agent/src/cli/memory/sync-github-artifacts.ts new file mode 100644 index 0000000..f912994 --- /dev/null +++ b/.agent/src/cli/memory/sync-github-artifacts.ts @@ -0,0 +1,552 @@ +#!/usr/bin/env node +// CLI: mirror issues / pull requests / discussions into the memory +// branch's github/ subtree as raw `gh --json` output. No LLM, no custom +// formatting — the agent grep-searches / jq-queries the JSON dumps directly. +// +// Emits cursors as step outputs so the outer workflow can persist them via +// write-sync-state. + +import { execFileSync } from "node:child_process"; +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; + +import { createGhGraphqlClient, type GraphQLClient } from "../../github-graphql.js"; +import { + discussionArtifactPath, + ensureMemoryStructure, + issueArtifactPath, + pullRequestArtifactPath, + writeFileIfChanged, +} from "../../memory-artifacts.js"; +import { setOutput } from "../../output.js"; + +const MAX_BUFFER = 32 * 1024 * 1024; +const DEFAULT_LOOKBACK_DAYS = 30; + +// Fields requested from `gh issue view` / `gh pr view`. We persist whatever +// gh gives us back verbatim. +const ISSUE_FIELDS = [ + "number", "title", "body", "url", "state", "author", "labels", + "createdAt", "updatedAt", "closedAt", "comments", +].join(","); + +const PR_FIELDS = [ + "number", "title", "body", "url", "state", "author", "labels", + "createdAt", "updatedAt", "closedAt", "mergedAt", "reviewDecision", + "headRefName", "baseRefName", "comments", "reviews", "files", +].join(","); + +interface WritableLike { write(chunk: string): void; } + +interface Args { + dir: string; + repo: string; + since: string; + startedAt: string; + lookbackDays: number; +} + +interface IssueListItem { + number: number; + updated_at?: string; + pull_request?: unknown; +} + +interface DiscussionNode { + number: number; + updatedAt?: string | null; +} + +interface DiscussionAuthorRecord { + login?: string | null; +} + +interface DiscussionReplyRecord { + id: string; + body?: string | null; + createdAt?: string | null; + url?: string | null; + author?: DiscussionAuthorRecord | null; + replyTo?: { id?: string | null } | null; +} + +interface DiscussionCommentRecord extends DiscussionReplyRecord { + replies?: { + nodes?: DiscussionReplyRecord[]; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; +} + +interface DiscussionPagePayload { + repository?: { + discussion?: { + number?: number | null; + title?: string | null; + url?: string | null; + body?: string | null; + createdAt?: string | null; + updatedAt?: string | null; + author?: DiscussionAuthorRecord | null; + category?: { name?: string | null } | null; + comments?: { + nodes?: DiscussionCommentRecord[]; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; + } | null; + } | null; +} + +interface DiscussionReplyPagePayload { + node?: { + replies?: { + nodes?: DiscussionReplyRecord[]; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; + } | null; +} + +interface DiscussionMirrorReply { + id: string; + body: string; + createdAt: string; + url: string; + author: { login: string } | null; + replyTo: { id: string } | null; +} + +interface DiscussionMirrorComment { + id: string; + body: string; + createdAt: string; + url: string; + author: { login: string } | null; + replies: { + nodes: DiscussionMirrorReply[]; + pageInfo: { hasNextPage: false; endCursor: null }; + }; +} + +interface DiscussionMirrorDetail { + number: number; + title: string; + url: string; + body: string; + createdAt: string; + updatedAt: string; + author: { login: string } | null; + category: { name: string } | null; + comments: { + nodes: DiscussionMirrorComment[]; + pageInfo: { hasNextPage: false; endCursor: null }; + }; +} + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + repo: { type: "string" }, + since: { type: "string" }, + "started-at": { type: "string" }, + "lookback-days": { type: "string" }, + }, + allowPositionals: false, + strict: true, +} as const satisfies ParseArgsConfig; + +function parsePositiveInt(value: string | undefined, fallback: number): number { + const parsed = Number(value ?? ""); + return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback; +} + +function parseCliArgs(argv: string[], env: NodeJS.ProcessEnv): Args { + const { values } = parseArgs({ ...ARG_CONFIG, args: argv }); + const dir = (values.dir as string | undefined) || env.MEMORY_DIR || process.cwd(); + const repo = (values.repo as string | undefined) || env.REPO_SLUG || env.GITHUB_REPOSITORY || ""; + const startedAt = (values["started-at"] as string | undefined) || env.MEMORY_SYNC_STARTED_AT || new Date().toISOString(); + const lookbackDays = parsePositiveInt( + (values["lookback-days"] as string | undefined) || env.MEMORY_SYNC_LOOKBACK_DAYS, + DEFAULT_LOOKBACK_DAYS, + ); + const explicitSince = (values.since as string | undefined) || env.MEMORY_SYNC_SINCE || ""; + const since = explicitSince || isoDaysAgo(startedAt, lookbackDays); + + return { dir: resolve(dir), repo, since, startedAt, lookbackDays }; +} + +function isoDaysAgo(fromIso: string, days: number): string { + return new Date(new Date(fromIso).getTime() - days * 86_400_000).toISOString(); +} + +function maxIso(a: string, b: string | undefined | null): string { + if (!b) return a; + return a >= b ? a : b; +} + +function ghJson(args: string[]): T { + return JSON.parse( + execFileSync("gh", args, { + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: MAX_BUFFER, + }).toString("utf8"), + ) as T; +} + +export function buildGhApiPagedArgs(endpoint: string, params: Array<[string, string]>): string[] { + const args = ["api", "--method", "GET", "--paginate", "--slurp", endpoint]; + for (const [flag, value] of params) args.push(flag, value); + return args; +} + +function ghApiPaged(endpoint: string, params: Array<[string, string]>): T[] { + const args = buildGhApiPagedArgs(endpoint, params); + return ghJson(args).flat(); +} + +function writeArtifact(path: string, data: unknown): boolean { + return writeFileIfChanged(path, JSON.stringify(data, null, 2) + "\n"); +} + +export function hasDiscussionsEnabled( + client: GraphQLClient, + owner: string, + repo: string, +): boolean { + const data = client.graphql<{ + repository?: { hasDiscussionsEnabled?: boolean | null } | null; + }>( + `query($owner:String!,$repo:String!){ + repository(owner:$owner,name:$repo){ + hasDiscussionsEnabled + } + }`, + { owner, repo }, + ); + + return data.repository?.hasDiscussionsEnabled === true; +} + +export function fetchDiscussions( + client: GraphQLClient, + owner: string, + repo: string, + since: string, +): DiscussionNode[] { + if (!hasDiscussionsEnabled(client, owner, repo)) { + return []; + } + + const out: DiscussionNode[] = []; + let after: string | undefined; + + while (true) { + const page = client.graphql<{ + repository?: { + discussions?: { + nodes?: DiscussionNode[]; + pageInfo?: { hasNextPage?: boolean; endCursor?: string | null } | null; + } | null; + } | null; + }>( + `query($owner:String!,$repo:String!,$after:String){ + repository(owner:$owner,name:$repo){ + discussions(first:100, after:$after, orderBy:{field:UPDATED_AT,direction:DESC}){ + nodes { number updatedAt } + pageInfo { hasNextPage endCursor } + } + } + }`, + { owner, repo, after }, + ); + + const nodes = page.repository?.discussions?.nodes ?? []; + let reachedOlder = false; + for (const node of nodes) { + if (since && node.updatedAt && node.updatedAt <= since) { + reachedOlder = true; + break; + } + out.push(node); + } + if (reachedOlder) break; + + const info = page.repository?.discussions?.pageInfo; + if (!info?.hasNextPage) break; + after = info.endCursor || undefined; + } + + return out; +} + +function fetchPaginatedDiscussionDetail( + client: GraphQLClient, + owner: string, + repo: string, + number: number, +): unknown { + let detail: DiscussionMirrorDetail | null = null; + const comments: DiscussionMirrorComment[] = []; + let after: string | undefined; + let hasNextPage = true; + + while (hasNextPage) { + const data = client.graphql( + `query($owner:String!,$repo:String!,$n:Int!,$after:String){ + repository(owner:$owner,name:$repo){ + discussion(number:$n){ + number title url body createdAt updatedAt + author { login } + category { name } + comments(first:100, after:$after) { + nodes { + id body createdAt url + author { login } + replies(first:100) { + nodes { + id body createdAt url + author { login } + replyTo { id } + } + pageInfo { hasNextPage endCursor } + } + } + pageInfo { hasNextPage endCursor } + } + } + } + }`, + { owner, repo, n: number, after }, + ); + + const discussion = data.repository?.discussion; + if (!discussion) return null; + + if (!detail) { + detail = { + number: discussion.number ?? number, + title: discussion.title || "", + url: discussion.url || "", + body: discussion.body || "", + createdAt: discussion.createdAt || "", + updatedAt: discussion.updatedAt || "", + author: discussion.author?.login ? { login: discussion.author.login } : null, + category: discussion.category?.name ? { name: discussion.category.name } : null, + comments: { + nodes: comments, + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }; + } + + for (const rawComment of discussion.comments?.nodes || []) { + const replies = (rawComment.replies?.nodes || []).map((reply) => ({ + id: reply.id, + body: reply.body || "", + createdAt: reply.createdAt || "", + url: reply.url || "", + author: reply.author?.login ? { login: reply.author.login } : null, + replyTo: reply.replyTo?.id ? { id: reply.replyTo.id } : null, + })); + + let replyAfter = rawComment.replies?.pageInfo?.endCursor || undefined; + let replyHasNextPage = rawComment.replies?.pageInfo?.hasNextPage || false; + + while (replyHasNextPage) { + const replyPage = client.graphql( + `query($commentId:ID!,$after:String){ + node(id:$commentId){ + ... on DiscussionComment { + replies(first:100, after:$after) { + nodes { + id body createdAt url + author { login } + replyTo { id } + } + pageInfo { hasNextPage endCursor } + } + } + } + }`, + { commentId: rawComment.id, after: replyAfter }, + ); + + const moreReplies = replyPage.node?.replies; + if (!moreReplies) break; + + replies.push( + ...(moreReplies.nodes || []).map((reply) => ({ + id: reply.id, + body: reply.body || "", + createdAt: reply.createdAt || "", + url: reply.url || "", + author: reply.author?.login ? { login: reply.author.login } : null, + replyTo: reply.replyTo?.id ? { id: reply.replyTo.id } : null, + })), + ); + replyAfter = moreReplies.pageInfo?.endCursor || undefined; + replyHasNextPage = moreReplies.pageInfo?.hasNextPage || false; + } + + comments.push({ + id: rawComment.id, + body: rawComment.body || "", + createdAt: rawComment.createdAt || "", + url: rawComment.url || "", + author: rawComment.author?.login ? { login: rawComment.author.login } : null, + replies: { + nodes: replies, + pageInfo: { hasNextPage: false, endCursor: null }, + }, + }); + } + + after = discussion.comments?.pageInfo?.endCursor || undefined; + hasNextPage = discussion.comments?.pageInfo?.hasNextPage || false; + } + + return detail; +} + +export function fetchDiscussionDetail( + client: GraphQLClient, + owner: string, + repo: string, + number: number, +): unknown { + return fetchPaginatedDiscussionDetail(client, owner, repo, number); +} + +export function runSyncGithubArtifactsCli( + argv: string[], + options: { + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + graphqlClient?: GraphQLClient; + } = {}, +): number { + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + + let args: Args; + try { + args = parseCliArgs(argv, env); + } catch (error: unknown) { + stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); + return 1; + } + + if (!args.repo || !args.repo.includes("/")) { + stderr.write(`Missing or invalid repository slug (got: ${args.repo || "empty"}). Set REPO_SLUG or GITHUB_REPOSITORY.\n`); + return 1; + } + + const [owner, repoName] = args.repo.split("/", 2) as [string, string]; + + try { + ensureMemoryStructure(args.dir, args.repo); + + // Issues + PRs come from one REST endpoint; the `pull_request` marker + // distinguishes them. + const issueLike = ghApiPaged(`repos/${args.repo}/issues`, [ + ["-f", "state=all"], + ["-f", `since=${args.since}`], + ["-f", "sort=updated"], + ["-f", "direction=asc"], + ["-F", "per_page=100"], + ]); + const issueItems = issueLike.filter((i) => !i.pull_request); + const pullItems = issueLike.filter((i) => Boolean(i.pull_request)); + + let changed = 0; + let issueCursor = args.startedAt; + let pullCursor = args.startedAt; + let lastActivityAt = ""; + + for (const item of issueItems) { + const data = ghJson<{ updatedAt?: string }>([ + "issue", "view", String(item.number), "--repo", args.repo, "--json", ISSUE_FIELDS, + ]); + if (writeArtifact(issueArtifactPath(args.dir, args.repo, item.number), data)) changed += 1; + issueCursor = maxIso(issueCursor, item.updated_at || data.updatedAt); + lastActivityAt = maxIso(lastActivityAt, item.updated_at || data.updatedAt); + } + + for (const item of pullItems) { + const data = ghJson<{ updatedAt?: string }>([ + "pr", "view", String(item.number), "--repo", args.repo, "--json", PR_FIELDS, + ]); + if (writeArtifact(pullRequestArtifactPath(args.dir, args.repo, item.number), data)) changed += 1; + pullCursor = maxIso(pullCursor, item.updated_at || data.updatedAt); + lastActivityAt = maxIso(lastActivityAt, item.updated_at || data.updatedAt); + } + + // Discussions: no `gh discussion` subcommand (cli/cli#3164) — use GraphQL. + const client = options.graphqlClient || createGhGraphqlClient(); + const discussionNodes = fetchDiscussions(client, owner, repoName, args.since); + let discussionCursor = args.startedAt; + + for (const node of discussionNodes) { + const detail = fetchDiscussionDetail(client, owner, repoName, node.number); + if (writeArtifact(discussionArtifactPath(args.dir, args.repo, node.number), detail)) changed += 1; + discussionCursor = maxIso(discussionCursor, node.updatedAt); + lastActivityAt = maxIso(lastActivityAt, node.updatedAt); + } + + // Compatibility-only: commit artifacts are no longer mirrored, but the + // workflows still pass these outputs into the sync-state writer. + const commitCursor = args.startedAt; + + setOutput("effective_since", args.since); + setOutput("issue_count", String(issueItems.length)); + setOutput("pull_count", String(pullItems.length)); + setOutput("discussion_count", String(discussionNodes.length)); + setOutput("commit_count", "0"); + setOutput("changed_files", String(changed)); + setOutput("last_activity_at", lastActivityAt); + setOutput("issue_cursor", issueCursor); + setOutput("pull_cursor", pullCursor); + setOutput("discussion_cursor", discussionCursor); + setOutput("commit_cursor", commitCursor); + + stdout.write( + `${JSON.stringify( + { + repo: args.repo, + memoryDir: args.dir, + effectiveSince: args.since, + issueCount: issueItems.length, + pullCount: pullItems.length, + discussionCount: discussionNodes.length, + commitCount: 0, + changedFiles: changed, + cursors: { + issues: issueCursor, + pulls: pullCursor, + discussions: discussionCursor, + commits: commitCursor, + }, + }, + null, + 2, + )}\n`, + ); + return 0; + } catch (error: unknown) { + stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runSyncGithubArtifactsCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/update.ts b/.agent/src/cli/memory/update.ts new file mode 100644 index 0000000..fddb2d1 --- /dev/null +++ b/.agent/src/cli/memory/update.ts @@ -0,0 +1,209 @@ +#!/usr/bin/env node +// CLI: update agent memory files with validated bullet-level edits. +// +// Usage: +// node .agent/dist/cli/memory/update.js add --file MEMORY.md --section Durable "" +// node .agent/dist/cli/memory/update.js replace --file MEMORY.md --section Durable --match "" --with "" +// node .agent/dist/cli/memory/update.js remove --file MEMORY.md --section Durable --match "" +// node .agent/dist/cli/memory/update.js daily-append "" +// +// Env: +// MEMORY_DIR fallback for --dir when not passed explicitly + +import { parseArgs, type ParseArgsConfig } from "node:util"; + +import { + addBullet, + appendDailyBullet, + isEditableFile, + removeBullet, + replaceBullet, + type EditableFile, + type UpdateResult, +} from "../../memory-update.js"; + +const USAGE = [ + "Usage: memory/update.js [options] [text]", + "", + "Subcommands:", + " add --file --section ", + " replace --file --section --match --with ", + " remove --file --section --match ", + " daily-append ", + "", + "Global options:", + " --dir Memory directory (defaults to MEMORY_DIR or cwd)", + " -h, --help Show this message", +].join("\n"); + +interface WritableLike { write(chunk: string): void; } + +const SUBCOMMANDS = ["add", "replace", "remove", "daily-append"] as const; +type Subcommand = typeof SUBCOMMANDS[number]; + +interface ParsedArgs { + subcommand: Subcommand | ""; + dir: string; + file: EditableFile | ""; + section: string; + match: string; + withText: string; + positional: string; + help: boolean; +} + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + file: { type: "string" }, + section: { type: "string" }, + match: { type: "string" }, + with: { type: "string" }, + help: { type: "boolean", short: "h", default: false }, + }, + allowPositionals: true, + strict: true, +} as const satisfies ParseArgsConfig; + +function isSubcommand(value: string): value is Subcommand { + return (SUBCOMMANDS as readonly string[]).includes(value); +} + +export function parseUpdateArgs( + argv: string[], + env: NodeJS.ProcessEnv = process.env, +): ParsedArgs { + const { values, positionals } = parseArgs({ ...ARG_CONFIG, args: argv }); + + const file = values.file as string | undefined; + if (file !== undefined && !isEditableFile(file)) { + throw new Error(`--file must be MEMORY.md or PROJECT.md (got ${file})`); + } + + let subcommand: Subcommand | "" = ""; + const rest = [...positionals]; + const first = rest.shift(); + if (first) { + if (!isSubcommand(first)) { + throw new Error(`Unknown subcommand: ${first}`); + } + subcommand = first; + } + + return { + subcommand, + dir: (values.dir as string | undefined) || env.MEMORY_DIR || process.cwd(), + file: (file as EditableFile | undefined) || "", + section: (values.section as string | undefined) || "", + match: (values.match as string | undefined) || "", + withText: (values.with as string | undefined) || "", + positional: rest.join(" ").trim(), + help: Boolean(values.help), + }; +} + +function describe(result: UpdateResult): { code: number; line: string } { + switch (result.action.kind) { + case "added": + return { code: 0, line: `added bullet to ${result.file}` }; + case "deduped": + return { code: 0, line: `collapsed duplicate bullet in ${result.file}` }; + case "replaced": + return { code: 0, line: `replaced bullet in ${result.file}` }; + case "removed": + return { code: 0, line: `removed bullet from ${result.file}` }; + case "noop": + return { code: 0, line: `no change (duplicate): ${result.file}` }; + case "missing_section": + return { code: 2, line: `section not found: ${result.action.section} in ${result.file}` }; + case "missing_match": + return { code: 2, line: `no bullet matched: ${result.action.match} in ${result.file}` }; + case "ambiguous_match": + return { + code: 2, + line: `multiple bullets matched: ${result.action.match} in ${result.file}\n${result.action.candidates.join("\n")}`, + }; + } +} + +export function runMemoryUpdateCli( + argv: string[], + options: { + env?: NodeJS.ProcessEnv; + stdout?: WritableLike; + stderr?: WritableLike; + } = {}, +): number { + const env = options.env || process.env; + const stdout = options.stdout || process.stdout; + const stderr = options.stderr || process.stderr; + + let parsed: ParsedArgs; + try { + parsed = parseUpdateArgs(argv, env); + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n\n${USAGE}\n`); + return 1; + } + + if (parsed.help || !parsed.subcommand) { + stdout.write(`${USAGE}\n`); + return parsed.help ? 0 : 1; + } + + try { + let result: UpdateResult; + switch (parsed.subcommand) { + case "add": { + if (!parsed.file) throw new Error("--file is required for add"); + if (!parsed.section) throw new Error("--section is required for add"); + if (!parsed.positional) throw new Error("bullet text is required for add"); + result = addBullet( + { root: parsed.dir, file: parsed.file, section: parsed.section }, + parsed.positional, + ); + break; + } + case "replace": { + if (!parsed.file) throw new Error("--file is required for replace"); + if (!parsed.section) throw new Error("--section is required for replace"); + if (!parsed.match) throw new Error("--match is required for replace"); + if (!parsed.withText) throw new Error("--with is required for replace"); + result = replaceBullet( + { root: parsed.dir, file: parsed.file, section: parsed.section }, + parsed.match, + parsed.withText, + ); + break; + } + case "remove": { + if (!parsed.file) throw new Error("--file is required for remove"); + if (!parsed.section) throw new Error("--section is required for remove"); + if (!parsed.match) throw new Error("--match is required for remove"); + result = removeBullet( + { root: parsed.dir, file: parsed.file, section: parsed.section }, + parsed.match, + ); + break; + } + case "daily-append": { + if (!parsed.positional) throw new Error("bullet text is required for daily-append"); + result = appendDailyBullet(parsed.dir, parsed.positional); + break; + } + } + + const { code, line } = describe(result); + (code === 0 ? stdout : stderr).write(`${line}\n`); + return code; + } catch (error: unknown) { + const message = error instanceof Error ? error.message : String(error); + stderr.write(`${message}\n`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runMemoryUpdateCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/memory/write-sync-state.ts b/.agent/src/cli/memory/write-sync-state.ts new file mode 100644 index 0000000..49b5c47 --- /dev/null +++ b/.agent/src/cli/memory/write-sync-state.ts @@ -0,0 +1,56 @@ +#!/usr/bin/env node +// CLI: update the ref-backed memory sync state with new cursors. + +import { configureBotIdentity } from "../../git.js"; +import { + createMemorySyncState, + fetchMemorySyncState, + memorySyncStateForRepo, + updateMemorySyncState, + writeMemorySyncState, + type PushOptions, +} from "../../memory-sync-state.js"; +import { setOutput } from "../../output.js"; + +function buildOptions(): PushOptions { + const repo = process.env.GITHUB_REPOSITORY || process.env.REPO_SLUG || ""; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + return { repo, token: token || undefined }; +} + +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const repoSlug = process.env.REPO_SLUG || process.env.GITHUB_REPOSITORY || ""; +const options = buildOptions(); +const lastSyncAt = process.env.SYNC_LAST_SYNC_AT || ""; +const lastActivityAt = process.env.SYNC_LAST_ACTIVITY_AT || ""; +const lastRunUrl = process.env.SYNC_LAST_RUN_URL || ""; + +setOutput("written", "false"); + +if (!repoSlug) { + console.error("Missing REPO_SLUG or GITHUB_REPOSITORY"); + process.exitCode = 2; +} else if (!lastSyncAt) { + console.error("Missing SYNC_LAST_SYNC_AT"); + process.exitCode = 2; +} else { + configureBotIdentity(cwd); + + const existing = memorySyncStateForRepo(fetchMemorySyncState(cwd, options), repoSlug) + || createMemorySyncState(repoSlug); + const next = updateMemorySyncState(existing, { + last_sync_at: lastSyncAt, + last_activity_at: lastActivityAt || existing.last_activity_at || lastSyncAt, + last_run_url: lastRunUrl, + cursors: { + issues: process.env.SYNC_ISSUE_CURSOR || existing.cursors.issues, + pulls: process.env.SYNC_PULL_CURSOR || existing.cursors.pulls, + discussions: process.env.SYNC_DISCUSSION_CURSOR || existing.cursors.discussions, + commits: process.env.SYNC_COMMIT_CURSOR || existing.cursors.commits, + }, + }); + + writeMemorySyncState(next, cwd, options); + setOutput("written", "true"); + process.stdout.write(`${JSON.stringify(next, null, 2)}\n`); +} diff --git a/.agent/src/cli/onboarding-check.ts b/.agent/src/cli/onboarding-check.ts new file mode 100644 index 0000000..ee75c80 --- /dev/null +++ b/.agent/src/cli/onboarding-check.ts @@ -0,0 +1,37 @@ +// CLI: ensure first-run Sepo labels and create/update the setup issue. +// Usage: node .agent/dist/cli/onboarding-check.js +// Env: GITHUB_REPOSITORY, AUTH_MODE, AGENT_PROVIDER, AGENT_PROVIDER_REASON, +// OPENAI_API_KEY_CONFIGURED, CLAUDE_CODE_OAUTH_TOKEN_CONFIGURED, +// MEMORY_REF, RUBRICS_REF, RUN_URL + +import { runOnboardingCheck } from "../onboarding.js"; +import { setOutput } from "../output.js"; + +function requiredEnv(name: string): string { + const value = process.env[name]?.trim() ?? ""; + if (!value) { + throw new Error(`${name} is required`); + } + return value; +} + +function isTrue(name: string): boolean { + return (process.env[name] || "").trim().toLowerCase() === "true"; +} + +const repo = requiredEnv("GITHUB_REPOSITORY"); +const issueNumber = runOnboardingCheck({ + repo, + authMode: process.env.AUTH_MODE || "", + provider: process.env.AGENT_PROVIDER || "", + providerReason: process.env.AGENT_PROVIDER_REASON || "", + openaiConfigured: isTrue("OPENAI_API_KEY_CONFIGURED"), + claudeConfigured: isTrue("CLAUDE_CODE_OAUTH_TOKEN_CONFIGURED"), + memoryRef: process.env.MEMORY_REF || "agent/memory", + rubricsRef: process.env.RUBRICS_REF || "agent/rubrics", + runUrl: process.env.RUN_URL || "", + runnerTemp: process.env.RUNNER_TEMP || "/tmp", +}); + +setOutput("issue_number", String(issueNumber)); +console.log(`Sepo onboarding issue is #${issueNumber}.`); diff --git a/.agent/src/cli/orchestrate-handoff.ts b/.agent/src/cli/orchestrate-handoff.ts new file mode 100644 index 0000000..845b320 --- /dev/null +++ b/.agent/src/cli/orchestrate-handoff.ts @@ -0,0 +1,1662 @@ +// CLI: post-action handoff orchestrator. +// Env: AUTOMATION_MODE, SOURCE_ACTION, SOURCE_CONCLUSION, TARGET_NUMBER, +// NEXT_TARGET_NUMBER, AUTOMATION_CURRENT_ROUND, AUTOMATION_MAX_ROUNDS, +// GITHUB_REPOSITORY, DEFAULT_BRANCH, REQUESTED_BY, REQUEST_TEXT, +// SESSION_BUNDLE_MODE, SOURCE_RUN_ID, PLANNER_RESPONSE_FILE, TARGET_KIND, +// BASE_BRANCH, BASE_PR, AGENT_COLLAPSE_OLD_REVIEWS, AGENT_ALLOW_SELF_APPROVE, +// AGENT_ALLOW_SELF_MERGE + +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { dispatchWorkflow, gh } from "../github.js"; +import { setOutput } from "../output.js"; +import { + type HandoffDecision, + type HandoffMarkerInfo, + buildHandoffDedupeKey, + decideHandoff, + defaultFixPrHandoffContext, + formatHandoffMarkerComment, + formatTransposedMarkdownTable, + isPendingHandoffMarkerStale, + normalizeAutomationMode, + parsePlannerDecision, + parseHandoffMarker, +} from "../handoff.js"; +import { initialOrchestrateCapabilityStopReason } from "../orchestrator-capabilities.js"; +import { collapsePreviousHandoffComments } from "../review-summary-minimize.js"; +import { + extractClosingIssueNumber, + formatSubOrchestrationIssueBody, + formatSubOrchestratorChildLinkMarker, + formatSubOrchestratorMarker, + normalizeSubOrchestratorStage, + parseSubOrchestratorChildLinkMarker, + parseSubOrchestratorMarker, + resultStateFromTerminal, + updateSubOrchestratorMarkerParentRound, + updateSubOrchestratorMarkerState, + type SubOrchestratorMarker, + type SubOrchestratorState, +} from "../sub-orchestration.js"; + +interface CommentRecord { + id?: string | number; + body?: string; + authorLogin?: string; +} + +interface HandoffMarkerRecord extends HandoffMarkerInfo { + id: string; +} + +interface IssueRecord { + number: number; + title: string; + body: string; + authorLogin?: string; + state?: string; + url?: string; +} + +interface TrustedSubOrchestratorMarkerRecord { + marker: SubOrchestratorMarker; + sourceKind: "body" | "comment"; + body: string; + commentId?: string; +} + +interface SubOrchestrationIssueRecord extends IssueRecord { + subOrchestrator: TrustedSubOrchestratorMarkerRecord; +} + +interface TerminalSubOrchestrationRejection { + issue: IssueRecord; + marker: SubOrchestratorMarker; + sourceLabel: string; + reason: string; + warning: string; +} + +type TerminalChildResolution = + | { kind: "trusted"; issue: SubOrchestrationIssueRecord } + | { kind: "rejected"; rejection: TerminalSubOrchestrationRejection } + | { kind: "none" }; + +const SUB_ORCHESTRATION_ADOPTION_COMMENT_MARKER = ""; +const ORCHESTRATE_STOP_MARKER = ""; +const TERMINAL_SUB_ORCHESTRATION_STOP_MARKER_PREFIX = "sepo-sub-orchestrator-terminal-stop"; +const PENDING_MARKER_TTL_MS = 60 * 60 * 1000; +const UNSATISFACTORY_ACTION_CONCLUSIONS = new Set(["no_changes", "failed", "verify_failed", "unsupported"]); + +function positiveInt(value: string, fallback: number): number { + const parsed = Number.parseInt(value, 10); + return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; +} + +function parsePositiveTargetNumber(value: string): number { + const parsed = Number.parseInt(value, 10); + return Number.isFinite(parsed) && parsed > 0 ? parsed : 0; +} + +function parseOptionalChildIssueNumber(value: string | undefined): number { + const text = String(value || "").trim(); + if (!text) return 0; + if (!/^\d+$/.test(text)) { + throw new Error(`child_issue_number must be a positive issue number: ${text}`); + } + const parsed = Number.parseInt(text, 10); + if (!Number.isSafeInteger(parsed) || parsed <= 0) { + throw new Error(`child_issue_number must be a positive issue number: ${text}`); + } + return parsed; +} + +function formatSubOrchestrationSelectionComment(input: { + parentIssue: number; + stage: string; + childIssue: number; +}): string { + const stage = normalizeSubOrchestratorStage(input.stage); + return [ + "Sepo is starting a focused child task for this orchestration.", + "", + ...formatTransposedMarkdownTable( + ["Child task", "Focus", "Parent issue", "Status"], + [`#${input.childIssue}`, stage, `#${input.parentIssue}`, "Running"], + ), + "", + "I'll report back here when the child task finishes.", + "", + formatSubOrchestratorChildLinkMarker({ parent: input.parentIssue, stage, child: input.childIssue }), + ].join("\n"); +} + +function formatSubOrchestrationOutcome(state: SubOrchestratorState): string { + switch (state) { + case "done": + return "Ready to ship"; + case "blocked": + return "Blocked"; + case "failed": + return "Failed"; + case "running": + return "Running"; + } +} + +function formatSubOrchestrationProgressComment(input: { + childIssue: number; + prNumber?: string; + resultState: SubOrchestratorState; + parentRound: number; + maxRounds: number; + summary: string; + marker: string; +}): string { + const headers = ["Child task"]; + const values: Array = [`#${input.childIssue}`]; + if (input.prNumber) { + headers.push("PR"); + values.push(`#${input.prNumber}`); + } + headers.push("Outcome", "Parent round", "Next step"); + values.push( + formatSubOrchestrationOutcome(input.resultState), + `${input.parentRound} / ${input.maxRounds}`, + "Resuming parent orchestration", + ); + + return [ + "Child task completed.", + "", + ...formatTransposedMarkdownTable(headers, values), + "", + `Summary: ${input.summary || "No summary provided."}`, + "", + input.marker, + ].join("\n"); +} + +function formatActorLoginForMessage(login: string | undefined): string { + const text = String(login || "").trim(); + return text ? `\`${text}\`` : "unknown author"; +} + +function formatTerminalSubOrchestrationStopMarker(input: { + childIssue: number; + parentIssue: number; +}): string { + return ``; +} + +function formatTerminalSubOrchestrationStopComment(input: { + rejection: TerminalSubOrchestrationRejection; + prNumber?: string; + marker: string; +}): string { + const headers = ["Child issue"]; + const values: Array = [`#${input.rejection.issue.number}`]; + if (input.prNumber) { + headers.push("PR"); + values.push(`#${input.prNumber}`); + } + headers.push("Parent issue", "Marker source", "Status"); + values.push(`#${input.rejection.marker.parent}`, input.rejection.sourceLabel, "Stopped"); + + return [ + "Sepo could not report this terminal child result to the parent.", + "", + ...formatTransposedMarkdownTable(headers, values), + "", + `Reason: ${input.rejection.reason}`, + "", + "No parent workflow was dispatched. Review the child marker before continuing manually.", + "", + input.marker, + ].join("\n"); +} + +function errorText(err: unknown): string { + const record = err as { message?: unknown; stderr?: unknown; stdout?: unknown }; + return [record.message, record.stderr, record.stdout] + .map((part) => { + if (Buffer.isBuffer(part)) return part.toString("utf8"); + return typeof part === "string" ? part : ""; + }) + .filter(Boolean) + .join("\n") || String(err); +} + +function extractLogin(value: unknown): string { + if (!value || typeof value !== "object" || Array.isArray(value)) return ""; + const login = (value as Record).login; + return typeof login === "string" ? login.trim() : ""; +} + +function authorLoginFromRecord(record: Record): string { + return extractLogin(record.author) || extractLogin(record.user); +} + +function normalizeActorLogin(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/^app\//i, "") + .replace(/\[bot\]$/i, ""); +} + +let authenticatedActorLogin: string | null = null; + +function fetchAuthenticatedActorLogin(): string { + if (authenticatedActorLogin !== null) return authenticatedActorLogin; + const raw = gh([ + "api", + "graphql", + "-f", + "query=query ViewerLogin { viewer { login } }", + ]).trim(); + const parsed = JSON.parse(raw || "{}") as { + data?: { viewer?: { login?: unknown } | null } | null; + viewer?: { login?: unknown } | null; + }; + const login = String(parsed.data?.viewer?.login || parsed.viewer?.login || "").trim(); + if (!login) throw new Error("Could not resolve authenticated GitHub actor login"); + authenticatedActorLogin = login; + return authenticatedActorLogin; +} + +function isTrustedActorLogin(authorLogin: string): boolean { + const normalizedAuthor = normalizeActorLogin(authorLogin); + if (!normalizedAuthor) return false; + return normalizedAuthor === normalizeActorLogin(fetchAuthenticatedActorLogin()); +} + +function isTrustedIssueRecord(issue: IssueRecord): boolean { + return isTrustedActorLogin(issue.authorLogin || ""); +} + +function normalizeCommentRecord(value: unknown): CommentRecord | null { + if (!value || typeof value !== "object" || Array.isArray(value)) return null; + const record = value as Record; + return { + id: record.id as string | number | undefined, + body: String(record.body || ""), + authorLogin: authorLoginFromRecord(record), + }; +} + +function fetchIssueComments(repo: string, issueNumber: number): CommentRecord[] { + const raw = gh([ + "api", + "--paginate", + "--slurp", + `repos/${repo}/issues/${issueNumber}/comments`, + ]).trim(); + if (!raw) return []; + + const parsed = JSON.parse(raw) as unknown; + const pages = Array.isArray(parsed) ? parsed : [parsed]; + const comments: CommentRecord[] = []; + for (const page of pages) { + const entries = Array.isArray(page) ? page : [page]; + for (const entry of entries) { + const comment = normalizeCommentRecord(entry); + if (comment) comments.push(comment); + } + } + return comments; +} + +function findHandoffMarkers( + repo: string, + issueNumber: number, + dedupeKey: string, +): HandoffMarkerRecord[] { + return fetchIssueComments(repo, issueNumber) + .map((comment) => { + const parsed = parseHandoffMarker(comment.body || "", dedupeKey); + if (!parsed || !isTrustedActorLogin(comment.authorLogin || "")) return null; + return { + id: String(comment.id || ""), + ...parsed, + }; + }) + .filter((marker): marker is HandoffMarkerRecord => Boolean(marker?.id)); +} + +function createIssueComment(repo: string, issueNumber: number, body: string): string { + return gh([ + "api", + "--method", + "POST", + `repos/${repo}/issues/${issueNumber}/comments`, + "-f", + `body=${body}`, + "--jq", + ".id", + ]).trim(); +} + +function updateIssueComment(repo: string, commentId: string, body: string): void { + gh([ + "api", + "--method", + "PATCH", + `repos/${repo}/issues/comments/${commentId}`, + "-f", + `body=${body}`, + ]); +} + +function fetchIssue(repoSlug: string, issueNumber: number): IssueRecord | null { + try { + return fetchIssueStrict(repoSlug, issueNumber); + } catch { + return null; + } +} + +function fetchIssueStrict(repoSlug: string, issueNumber: number): IssueRecord { + const raw = gh([ + "issue", + "view", + String(issueNumber), + "--repo", + repoSlug, + "--json", + "number,title,body,author,state,url", + ]).trim(); + if (!raw) throw new Error(`empty issue response for #${issueNumber}`); + const parsed = JSON.parse(raw) as Record; + return { + number: Number(parsed.number || issueNumber), + title: String(parsed.title || ""), + body: String(parsed.body || ""), + authorLogin: authorLoginFromRecord(parsed), + state: String(parsed.state || ""), + url: String(parsed.url || ""), + }; +} + +function withTempBodyFile(body: string, fn: (path: string) => T): T { + const dir = mkdtempSync(join(tmpdir(), "sepo-sub-orchestrator-")); + try { + const file = join(dir, "body.md"); + writeFileSync(file, body, "utf8"); + return fn(file); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +} + +function updateIssueBody(repoSlug: string, issueNumber: number, body: string): void { + withTempBodyFile(body, (bodyFile) => { + gh(["issue", "edit", String(issueNumber), "--repo", repoSlug, "--body-file", bodyFile]); + }); +} + +function createIssueFromBody(repoSlug: string, title: string, body: string): string { + return withTempBodyFile(body, (bodyFile) => gh([ + "issue", + "create", + "--repo", + repoSlug, + "--title", + title, + "--body-file", + bodyFile, + ]).trim()); +} + +function parseIssueNumberFromUrl(url: string): string { + const match = String(url || "").trim().match(/\/issues\/(\d+)(?:\D*)?$/); + return match ? match[1] : ""; +} + +function trustedSubOrchestratorMarkerFromBody(issue: IssueRecord): TrustedSubOrchestratorMarkerRecord | null { + const marker = parseSubOrchestratorMarker(issue.body); + if (!marker || !isTrustedIssueRecord(issue)) return null; + return { marker, sourceKind: "body", body: issue.body }; +} + +function isSubOrchestrationAdoptionComment(body: string): boolean { + const text = String(body || "").trim(); + return ( + text.startsWith("Sepo adopted this issue as a sub-orchestrator child of #") && + text.includes(SUB_ORCHESTRATION_ADOPTION_COMMENT_MARKER) + ); +} + +function trustedSubOrchestratorMarkerFromComments( + repoSlug: string, + issueNumber: number, +): TrustedSubOrchestratorMarkerRecord | null { + for (const comment of [...fetchIssueComments(repoSlug, issueNumber)].reverse()) { + const body = comment.body || ""; + const marker = parseSubOrchestratorMarker(body); + if ( + !marker || + !comment.id || + !isTrustedActorLogin(comment.authorLogin || "") || + !isSubOrchestrationAdoptionComment(body) + ) { + continue; + } + return { + marker, + sourceKind: "comment", + body, + commentId: String(comment.id), + }; + } + return null; +} + +function trustedSubOrchestrationIssue( + repoSlug: string, + issue: IssueRecord, +): SubOrchestrationIssueRecord | null { + const subOrchestrator = trustedSubOrchestratorMarkerFromBody(issue) || + trustedSubOrchestratorMarkerFromComments(repoSlug, issue.number); + return subOrchestrator ? { ...issue, subOrchestrator } : null; +} + +function resolveTerminalSubOrchestrationIssue( + repoSlug: string, + issue: IssueRecord, +): TerminalChildResolution { + let rejection: TerminalSubOrchestrationRejection | null = null; + + const bodyMarker = parseSubOrchestratorMarker(issue.body); + if (bodyMarker) { + if (isTrustedIssueRecord(issue)) { + return { + kind: "trusted", + issue: { + ...issue, + subOrchestrator: { marker: bodyMarker, sourceKind: "body", body: issue.body }, + }, + }; + } + rejection = { + issue, + marker: bodyMarker, + sourceLabel: "Issue body", + reason: `The child issue body marker was authored by ${formatActorLoginForMessage(issue.authorLogin)}, not the authenticated Sepo actor.`, + warning: `Ignoring untrusted terminal sub-orchestrator marker in issue #${issue.number} body from ${issue.authorLogin || "unknown author"}`, + }; + } + + for (const comment of [...fetchIssueComments(repoSlug, issue.number)].reverse()) { + const body = comment.body || ""; + const marker = parseSubOrchestratorMarker(body); + if (!marker || !isSubOrchestrationAdoptionComment(body)) { + continue; + } + if (!comment.id) { + rejection ??= { + issue, + marker, + sourceLabel: "Adoption comment", + reason: "The child adoption marker comment is missing a GitHub comment id, so Sepo cannot safely update it.", + warning: `Ignoring unresolvable terminal sub-orchestrator adoption marker in issue #${issue.number} comment unknown from ${comment.authorLogin || "unknown author"}`, + }; + continue; + } + if (!isTrustedActorLogin(comment.authorLogin || "")) { + rejection ??= { + issue, + marker, + sourceLabel: `Adoption comment ${comment.id}`, + reason: `The child adoption marker comment was authored by ${formatActorLoginForMessage(comment.authorLogin)}, not the authenticated Sepo actor.`, + warning: `Ignoring untrusted terminal sub-orchestrator adoption marker in issue #${issue.number} comment ${comment.id || "unknown"} from ${comment.authorLogin || "unknown author"}`, + }; + continue; + } + return { + kind: "trusted", + issue: { + ...issue, + subOrchestrator: { + marker, + sourceKind: "comment", + body, + commentId: String(comment.id), + }, + }, + }; + } + return rejection ? { kind: "rejected", rejection } : { kind: "none" }; +} + +function updateTrustedSubOrchestratorMarker( + repoSlug: string, + issue: SubOrchestrationIssueRecord, + body: string, +): void { + if (issue.subOrchestrator.sourceKind === "body") { + updateIssueBody(repoSlug, issue.number, body); + return; + } + if (!issue.subOrchestrator.commentId) { + throw new Error(`child issue #${issue.number} marker comment is missing an id`); + } + updateIssueComment(repoSlug, issue.subOrchestrator.commentId, body); +} + +function updateSubOrchestrationParentRound( + repoSlug: string, + issue: SubOrchestrationIssueRecord, + parentRound: number, +): void { + const updatedBody = updateSubOrchestratorMarkerParentRound(issue.subOrchestrator.body, parentRound); + if (updatedBody !== issue.subOrchestrator.body) { + updateTrustedSubOrchestratorMarker(repoSlug, issue, updatedBody); + } +} + +function findExistingSubOrchestrationIssue( + repoSlug: string, + parentIssue: number, + stage: string, +): SubOrchestrationIssueRecord | null { + const expectedStage = normalizeSubOrchestratorStage(stage); + const raw = gh([ + "issue", + "list", + "--repo", + repoSlug, + "--state", + "open", + "--search", + "sepo-sub-orchestrator", + "--json", + "number,title,body,author", + "--limit", + "100", + ]).trim(); + const parsed = JSON.parse(raw || "[]") as unknown; + if (!Array.isArray(parsed)) { + throw new Error("could not parse existing sub-orchestrator issue search results"); + } + for (const entry of parsed) { + if (!entry || typeof entry !== "object") continue; + const record = entry as Record; + const number = parsePositiveTargetNumber(String(record.number || "")); + const issue: IssueRecord = { + number, + title: String(record.title || ""), + body: String(record.body || ""), + authorLogin: authorLoginFromRecord(record), + }; + const markerRecord = number ? trustedSubOrchestratorMarkerFromBody(issue) : null; + const marker = markerRecord?.marker; + if (markerRecord && marker?.parent === parentIssue && marker.stage === expectedStage && marker.state === "running") { + return { ...issue, subOrchestrator: markerRecord }; + } + } + return null; +} + +function findRecordedSubOrchestrationIssue( + repoSlug: string, + parentIssue: number, + stage: string, +): SubOrchestrationIssueRecord | null { + const expectedStage = normalizeSubOrchestratorStage(stage); + const comments = fetchIssueComments(repoSlug, parentIssue); + for (const comment of [...comments].reverse()) { + const link = parseSubOrchestratorChildLinkMarker(comment.body || ""); + if (!link || link.parent !== parentIssue || link.stage !== expectedStage) continue; + if (!isTrustedActorLogin(comment.authorLogin || "")) continue; + + const existing = fetchIssue(repoSlug, link.child); + if (!existing) throw new Error(`Could not read recorded child issue #${link.child}`); + const subIssue = trustedSubOrchestrationIssue(repoSlug, existing); + if (!subIssue) { + throw new Error(`recorded child issue #${link.child} is missing a trusted sepo-sub-orchestrator marker`); + } + validateReusableChildIssue(subIssue, parentIssue, stage); + return subIssue; + } + return null; +} + +function hasRecordedSubOrchestrationIssue( + repoSlug: string, + parentIssue: number, + stage: string, + childIssue: number, +): boolean { + const expectedStage = normalizeSubOrchestratorStage(stage); + return fetchIssueComments(repoSlug, parentIssue).some((comment) => { + const link = parseSubOrchestratorChildLinkMarker(comment.body || ""); + return Boolean( + link && + link.parent === parentIssue && + link.stage === expectedStage && + link.child === childIssue && + isTrustedActorLogin(comment.authorLogin || ""), + ); + }); +} + +function fetchIssueDatabaseId(repoSlug: string, issueNumber: number): number { + const raw = gh([ + "api", + `repos/${repoSlug}/issues/${issueNumber}`, + "--jq", + ".id", + ]).trim(); + const parsed = Number.parseInt(raw, 10); + if (!Number.isSafeInteger(parsed) || parsed <= 0) { + throw new Error(`could not resolve database id for issue #${issueNumber}`); + } + return parsed; +} + +function hasGitHubSubIssueRelation(repoSlug: string, parentIssue: number, childIssue: number): boolean { + try { + const raw = gh([ + "api", + "--paginate", + `repos/${repoSlug}/issues/${parentIssue}/sub_issues`, + "--jq", + ".[].number", + ]).trim(); + return raw.split(/\r?\n/).some((line) => parsePositiveTargetNumber(line) === childIssue); + } catch { + return false; + } +} + +function ensureGitHubSubIssueRelation(repoSlug: string, parentIssue: number, childIssue: number): void { + if (hasGitHubSubIssueRelation(repoSlug, parentIssue, childIssue)) return; + + try { + const childIssueId = fetchIssueDatabaseId(repoSlug, childIssue); + gh([ + "api", + "--method", + "POST", + `repos/${repoSlug}/issues/${parentIssue}/sub_issues`, + "-F", + `sub_issue_id=${childIssueId}`, + "--silent", + ]); + } catch (err: unknown) { + console.warn( + `Could not link child issue #${childIssue} as a GitHub sub-issue of #${parentIssue}: ${errorText(err)}`, + ); + } +} + +function recordSubOrchestrationIssue(repoSlug: string, parentIssue: number, stage: string, childIssue: number): void { + if (!hasRecordedSubOrchestrationIssue(repoSlug, parentIssue, stage, childIssue)) { + createIssueComment(repoSlug, parentIssue, formatSubOrchestrationSelectionComment({ + parentIssue, + stage, + childIssue, + })); + } + ensureGitHubSubIssueRelation(repoSlug, parentIssue, childIssue); +} + +function formatSubOrchestrationAdoptionComment(input: { + parentIssue: number; + stage: string; + parentRound: number; +}): string { + const stage = normalizeSubOrchestratorStage(input.stage); + return [ + `Sepo adopted this issue as a sub-orchestrator child of #${input.parentIssue}.`, + "", + ...formatTransposedMarkdownTable( + ["Parent issue", "Stage", "Parent round", "Status"], + [`#${input.parentIssue}`, stage, input.parentRound, "Running"], + ), + "", + formatSubOrchestratorMarker({ + parent: input.parentIssue, + stage, + parentRound: input.parentRound, + }), + SUB_ORCHESTRATION_ADOPTION_COMMENT_MARKER, + ].join("\n"); +} + +function adoptExistingSubOrchestrationIssue( + repoSlug: string, + existing: IssueRecord, + parentIssue: number, + stage: string, + parentRound: number, +): SubOrchestrationIssueRecord { + if (existing.number === parentIssue) { + throw new Error(`child issue #${existing.number} cannot be the parent issue`); + } + const body = formatSubOrchestrationAdoptionComment({ parentIssue, stage, parentRound }); + const commentId = createIssueComment(repoSlug, existing.number, body); + const marker = parseSubOrchestratorMarker(body); + if (!marker) throw new Error(`could not create sub-orchestrator marker for child issue #${existing.number}`); + return { + ...existing, + subOrchestrator: { + marker, + sourceKind: "comment", + body, + commentId, + }, + }; +} + +function validateExplicitChildIssueTarget(existing: IssueRecord): void { + if (/\/pull\/\d+(?:\D*)?$/.test(existing.url || "")) { + throw new Error(`child_issue_number #${existing.number} is a pull request, not an issue`); + } + if (!/\/issues\/\d+(?:\D*)?$/.test(existing.url || "")) { + throw new Error(`child_issue_number #${existing.number} could not be verified as an issue`); + } + const state = String(existing.state || "").trim().toUpperCase(); + if (state !== "OPEN") { + throw new Error(`child_issue_number #${existing.number} is ${state ? state.toLowerCase() : "not open"}, not open`); + } +} + +function validateReusableChildIssue( + existing: SubOrchestrationIssueRecord, + parentIssue: number, + stage: string, +): void { + const marker = existing.subOrchestrator.marker; + const expectedStage = normalizeSubOrchestratorStage(stage); + if (marker.parent !== parentIssue) { + throw new Error(`child issue #${existing.number} belongs to parent #${marker.parent}, not #${parentIssue}`); + } + if (marker.stage !== expectedStage) { + throw new Error(`child issue #${existing.number} is stage ${marker.stage}, not ${expectedStage}`); + } + if (marker.state !== "running") { + throw new Error(`child issue #${existing.number} is ${marker.state}, not reusable`); + } +} + +function resolveEffectiveBaseInputs(decision: HandoffDecision): { baseBranch: string; basePr: string } { + return { + baseBranch: decision.baseBranch || baseBranch, + basePr: decision.basePr || basePr, + }; +} + +function ensureSubOrchestrationIssue(decision: HandoffDecision): string { + const parentIssue = parsePositiveTargetNumber(targetNumber); + if (!parentIssue) throw new Error(`Invalid parent issue number: ${targetNumber}`); + const { baseBranch: effectiveBaseBranch, basePr: effectiveBasePr } = resolveEffectiveBaseInputs(decision); + if (effectiveBaseBranch && effectiveBasePr) { + throw new Error("set only one of base_branch or base_pr for child orchestration"); + } + + const stage = decision.childStage || `stage-${decision.nextRound - 1}`; + const instructions = decision.childInstructions || decision.handoffContext || requestText; + const existingIssueNumber = parseOptionalChildIssueNumber(decision.childIssueNumber); + const parentRound = decision.nextRound; + + if (existingIssueNumber) { + const existing = fetchIssue(repo, existingIssueNumber); + if (!existing) throw new Error(`Could not read child issue #${existingIssueNumber}`); + validateExplicitChildIssueTarget(existing); + const trustedIssue = trustedSubOrchestrationIssue(repo, existing); + const childIssue = trustedIssue || adoptExistingSubOrchestrationIssue( + repo, + existing, + parentIssue, + stage, + parentRound, + ); + validateReusableChildIssue(childIssue, parentIssue, stage); + updateSubOrchestrationParentRound(repo, childIssue, parentRound); + recordSubOrchestrationIssue(repo, parentIssue, stage, childIssue.number); + return String(existingIssueNumber); + } + + const recordedIssue = findRecordedSubOrchestrationIssue(repo, parentIssue, stage); + if (recordedIssue) { + updateSubOrchestrationParentRound(repo, recordedIssue, parentRound); + ensureGitHubSubIssueRelation(repo, parentIssue, recordedIssue.number); + return String(recordedIssue.number); + } + + const reusableIssue = findExistingSubOrchestrationIssue(repo, parentIssue, stage); + if (reusableIssue) { + updateSubOrchestrationParentRound(repo, reusableIssue, parentRound); + recordSubOrchestrationIssue(repo, parentIssue, stage, reusableIssue.number); + return String(reusableIssue.number); + } + + const title = `Sub-orchestrator: ${stage}`; + const body = formatSubOrchestrationIssueBody({ + parentIssue, + stage, + taskInstructions: instructions, + baseBranch: effectiveBaseBranch, + basePr: effectiveBasePr, + parentRound, + }); + const createdUrl = createIssueFromBody(repo, title, body); + const createdNumber = parseIssueNumberFromUrl(createdUrl); + if (!createdNumber) throw new Error(`Could not parse created child issue URL: ${createdUrl}`); + recordSubOrchestrationIssue(repo, parentIssue, stage, parsePositiveTargetNumber(createdNumber)); + return createdNumber; +} + +const repo = process.env.GITHUB_REPOSITORY || ""; +const ref = process.env.DEFAULT_BRANCH || ""; +const sourceAction = process.env.SOURCE_ACTION || ""; +const sourceConclusion = process.env.SOURCE_CONCLUSION || "unknown"; +const sourceRunId = process.env.SOURCE_RUN_ID || process.env.GITHUB_RUN_ID || ""; +const sourceRecommendedNextStep = process.env.SOURCE_RECOMMENDED_NEXT_STEP || ""; +const sourceHandoffContext = process.env.SOURCE_HANDOFF_CONTEXT || ""; +const sourceTargetKind = process.env.TARGET_KIND || ""; +const sourceAssociationRaw = process.env.AUTHOR_ASSOCIATION || ""; +const accessPolicyRaw = process.env.ACCESS_POLICY || ""; +const isPublicRepo = String(process.env.REPOSITORY_PRIVATE || "").trim().toLowerCase() === "false"; +const targetNumber = process.env.TARGET_NUMBER || ""; +const requestedBy = process.env.REQUESTED_BY || ""; +const requestText = process.env.REQUEST_TEXT || ""; +const sessionBundleMode = process.env.SESSION_BUNDLE_MODE || ""; +const baseBranch = process.env.BASE_BRANCH || ""; +const basePr = process.env.BASE_PR || ""; +const maxRounds = positiveInt(process.env.AUTOMATION_MAX_ROUNDS || "", 12); +const currentRound = positiveInt(process.env.AUTOMATION_CURRENT_ROUND || "", 1); +const automationMode = normalizeAutomationMode(process.env.AUTOMATION_MODE || "disabled"); +const allowSelfApprove = ["true", "1", "yes", "on"].includes( + normalizeToken(process.env.AGENT_ALLOW_SELF_APPROVE || ""), +); +const allowSelfMerge = ["true", "1", "yes", "on"].includes( + normalizeToken(process.env.AGENT_ALLOW_SELF_MERGE || ""), +); +const collapseOldReviews = !["false", "0", "no", "off"].includes( + (process.env.AGENT_COLLAPSE_OLD_REVIEWS || "").trim().toLowerCase(), +); + +function manualPrChangesRequestedFixPrHandoffContext(): string { + return [ + "Address the latest unresolved requested-change review comments on this pull request.", + "Treat those requested-change comments as the selected fix-pr task; do not use review-synthesis-only defaults when no synthesis exists.", + "Ignore optional INFO notes, metadata-only polish, already-fixed findings, and human-judgment nits unless required by the requested changes.", + ].join(" "); +} + +function fallbackFixPrHandoffContext(): string { + const explicitContext = sourceHandoffContext.trim(); + if (explicitContext) return explicitContext; + const normalizedSourceAction = normalizeToken(sourceAction); + if (normalizedSourceAction === "orchestrate" && normalizeToken(sourceTargetKind) === "pull_request") { + return manualPrChangesRequestedFixPrHandoffContext(); + } + if (normalizedSourceAction === "review") { + return defaultFixPrHandoffContext(); + } + return ""; +} + +function readPlannerDecision(): ReturnType { + const responseFile = process.env.PLANNER_RESPONSE_FILE || ""; + if (!responseFile) return null; + try { + return parsePlannerDecision(readFileSync(responseFile, "utf8")); + } catch { + return null; + } +} + +function normalizeToken(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +function readPrStatus(repoSlug: string, prNumber: string): { state: string; reviewDecision: string } | null { + try { + const raw = gh([ + "pr", + "view", + prNumber, + "--repo", + repoSlug, + "--json", + "state,reviewDecision", + ]).trim(); + if (!raw) return null; + const parsed = JSON.parse(raw) as Record; + return { + state: String(parsed.state || "").trim().toUpperCase(), + reviewDecision: String(parsed.reviewDecision || "").trim().toUpperCase(), + }; + } catch { + return null; + } +} + +function readPrBodyStrict(repoSlug: string, prNumber: string): string { + const raw = gh(["pr", "view", prNumber, "--repo", repoSlug, "--json", "body"]).trim(); + if (!raw) throw new Error(`empty pull request response for #${prNumber}`); + const parsed = JSON.parse(raw) as Record; + return String(parsed.body || ""); +} + +function resolveChildIssueForTerminal(): TerminalChildResolution { + const normalizedKind = normalizeToken(sourceTargetKind); + const currentNumber = parsePositiveTargetNumber(targetNumber); + if (!repo || !currentNumber) return { kind: "none" }; + if (normalizedKind === "issue") { + return resolveTerminalSubOrchestrationIssue(repo, fetchIssueStrict(repo, currentNumber)); + } + if (normalizedKind === "pull_request") { + const linkedIssueNumber = extractClosingIssueNumber(readPrBodyStrict(repo, targetNumber), repo); + if (!linkedIssueNumber) return { kind: "none" }; + return resolveTerminalSubOrchestrationIssue(repo, fetchIssueStrict(repo, linkedIssueNumber)); + } + return { kind: "none" }; +} + +function hasTrustedTerminalSubOrchestrationStopComment(repoSlug: string, issueNumber: number, marker: string): boolean { + try { + return fetchIssueComments(repoSlug, issueNumber).some((comment) => + String(comment.body || "").includes(marker) && isTrustedActorLogin(comment.authorLogin || "") + ); + } catch (err: unknown) { + console.warn(`Failed to inspect existing terminal sub-orchestration stop comments: ${errorText(err)}`); + return false; + } +} + +function commentOnTerminalSubOrchestrationRejection(rejection: TerminalSubOrchestrationRejection): void { + console.warn(rejection.warning); + const target = parsePositiveTargetNumber(targetNumber); + if (!repo || !target || !["issue", "pull_request"].includes(normalizeToken(sourceTargetKind))) { + return; + } + const marker = formatTerminalSubOrchestrationStopMarker({ + childIssue: rejection.issue.number, + parentIssue: rejection.marker.parent, + }); + if (hasTrustedTerminalSubOrchestrationStopComment(repo, target, marker)) { + return; + } + const prNumber = normalizeToken(sourceTargetKind) === "pull_request" ? targetNumber : ""; + createIssueComment(repo, target, formatTerminalSubOrchestrationStopComment({ + rejection, + prNumber, + marker, + })); +} + +function reportTerminalToParent(decision: HandoffDecision): void { + const childResolution = resolveChildIssueForTerminal(); + if (childResolution.kind === "none") return; + if (childResolution.kind === "rejected") { + commentOnTerminalSubOrchestrationRejection(childResolution.rejection); + return; + } + const childIssue = childResolution.issue; + const marker = childIssue.subOrchestrator.marker; + if (!["running", "done", "blocked", "failed"].includes(marker.state)) return; + + const resultState = marker.state === "running" ? resultStateFromTerminal({ + sourceAction, + sourceConclusion, + reason: decision.reason, + }) : marker.state; + const parentRound = marker.parentRound || 1; + const prNumber = normalizeToken(sourceTargetKind) === "pull_request" ? targetNumber : ""; + const progressMarkerPrefix = `sepo-sub-orchestrator-report child:${childIssue.number}`; + const pendingProgressMarker = ``; + const dispatchedProgressMarker = ``; + + const progressComments = fetchIssueComments(repo, marker.parent).filter((comment) => + String(comment.body || "").includes(progressMarkerPrefix) && isTrustedActorLogin(comment.authorLogin || "") + ); + const existingProgress = progressComments[progressComments.length - 1]; + const progressWasDispatched = String(existingProgress?.body || "").includes(dispatchedProgressMarker); + if (marker.state !== "running" && progressWasDispatched) { + return; + } + let progressCommentId = existingProgress?.id ? String(existingProgress.id) : ""; + const writeProgress = (progressMarker: string): void => { + const progressBody = formatSubOrchestrationProgressComment({ + childIssue: childIssue.number, + prNumber, + resultState, + parentRound, + maxRounds, + summary: decision.reason, + marker: progressMarker, + }); + if (progressCommentId) { + updateIssueComment(repo, progressCommentId, progressBody); + } else { + progressCommentId = createIssueComment(repo, marker.parent, progressBody); + } + }; + + if (!progressWasDispatched) { + writeProgress(pendingProgressMarker); + + dispatchWorkflow(repo, "agent-orchestrator.yml", ref, { + source_action: "orchestrate", + source_conclusion: resultState, + source_run_id: sourceRunId, + target_kind: "issue", + target_number: String(marker.parent), + requested_by: requestedBy, + request_text: `Child issue #${childIssue.number} finished with ${ + resultState === "done" ? "SHIP" : resultState.toUpperCase() + }: ${decision.reason}`, + automation_mode: "agent", + automation_current_round: String(parentRound), + automation_max_rounds: String(maxRounds), + session_bundle_mode: sessionBundleMode, + base_branch: baseBranch, + base_pr: basePr, + }); + + writeProgress(dispatchedProgressMarker); + } + + const updatedChildMarkerBody = marker.state === "running" + ? updateSubOrchestratorMarkerState(childIssue.subOrchestrator.body, resultState as SubOrchestratorState) + : childIssue.subOrchestrator.body; + if (updatedChildMarkerBody !== childIssue.subOrchestrator.body) { + updateTrustedSubOrchestratorMarker(repo, childIssue, updatedChildMarkerBody); + } +} + +function pushUniqueMarkdownBlock(lines: string[], value: string | undefined): void { + const text = String(value || "").trim(); + if (!text || lines.includes(text)) return; + lines.push(text); +} + +function formatPlannerClarificationComment(decision: HandoffDecision): string | null { + if (decision.plannerDecisionKind !== "blocked") { + return null; + } + + const messageLines: string[] = []; + pushUniqueMarkdownBlock(messageLines, decision.userMessage); + if (decision.clarificationRequest) { + pushUniqueMarkdownBlock(messageLines, `Clarification request: ${decision.clarificationRequest}`); + } + if (!messageLines.length) { + return null; + } + + const lines = [ + "Sepo orchestration needs clarification before it can continue.", + "", + ...messageLines.flatMap((message, index) => index === 0 ? [message] : ["", message]), + "", + `- Source action: \`${sourceAction || "unknown"}\``, + `- Source conclusion: \`${sourceConclusion || "unknown"}\``, + `- Target: \`${sourceTargetKind || "unknown"} #${targetNumber || "unknown"}\``, + `- Round: \`${currentRound}/${maxRounds}\``, + `- Reason: ${decision.reason}`, + ]; + + if (sourceRunId) { + lines.push(`- Source run ID: \`${sourceRunId}\``); + } + + lines.push( + "", + "No follow-up workflow was dispatched. Reply with the requested context, then continue with `/orchestrate`, `/implement`, or `/answer` when ready.", + "", + ORCHESTRATE_STOP_MARKER, + ); + return lines.join("\n"); +} + +function formatPlannerAnswerComment(decision: HandoffDecision): string | null { + if (decision.plannerDecisionKind !== "answer") { + return null; + } + + const message = String(decision.userMessage || "").trim(); + if (!message) return null; + + const lines = [ + "Sepo answered this orchestration request.", + "", + message, + "", + `- Source action: \`${sourceAction || "unknown"}\``, + `- Source conclusion: \`${sourceConclusion || "unknown"}\``, + `- Target: \`${sourceTargetKind || "unknown"} #${targetNumber || "unknown"}\``, + `- Round: \`${currentRound}/${maxRounds}\``, + `- Reason: ${decision.reason}`, + ]; + + if (sourceRunId) { + lines.push(`- Source run ID: \`${sourceRunId}\``); + } + + lines.push("", ORCHESTRATE_STOP_MARKER); + return lines.join("\n"); +} + +function formatOrchestrateStopComment(decision: HandoffDecision): string { + const clarificationComment = formatPlannerClarificationComment(decision); + if (clarificationComment) { + return clarificationComment; + } + const answerComment = formatPlannerAnswerComment(decision); + if (answerComment) { + return answerComment; + } + + const lines = [ + `Sepo orchestration stopped after \`${sourceAction || "unknown"}\` concluded \`${sourceConclusion || "unknown"}\`.`, + "", + `- Source action: \`${sourceAction || "unknown"}\``, + `- Source conclusion: \`${sourceConclusion || "unknown"}\``, + `- Target: \`${sourceTargetKind || "unknown"} #${targetNumber || "unknown"}\``, + `- Round: \`${currentRound}/${maxRounds}\``, + `- Reason: ${decision.reason}`, + ]; + + if (sourceRunId) { + lines.push(`- Source run ID: \`${sourceRunId}\``); + } + + lines.push( + "", + "No follow-up workflow was dispatched. Inspect the source action status comment and workflow logs before retrying or continuing manually.", + "", + ORCHESTRATE_STOP_MARKER, + ); + return lines.join("\n"); +} + +function hasMatchingOrchestrateStopComment(repoSlug: string, issueNumber: number, body: string): boolean { + try { + const expectedBody = body.trim(); + return fetchIssueComments(repoSlug, issueNumber).some((comment) => { + const commentBody = String(comment.body || ""); + return ( + commentBody.includes(ORCHESTRATE_STOP_MARKER) && + commentBody.trim() === expectedBody && + isTrustedActorLogin(comment.authorLogin || "") + ); + }); + } catch (err: unknown) { + console.warn(`Failed to inspect existing orchestrator stop comments: ${errorText(err)}`); + return false; + } +} + +function createOrchestrateStopComment(decision: HandoffDecision): void { + const target = parsePositiveTargetNumber(targetNumber); + if (!repo || !target || !["issue", "pull_request"].includes(normalizeToken(sourceTargetKind))) { + return; + } + const body = formatOrchestrateStopComment(decision); + if (hasMatchingOrchestrateStopComment(repo, target, body)) { + return; + } + createIssueComment(repo, target, body); +} + +function commentOnInitialOrchestrateStop(decision: HandoffDecision): void { + if (formatPlannerClarificationComment(decision) || formatPlannerAnswerComment(decision)) { + return; + } + if ( + normalizeToken(sourceAction) !== "orchestrate" || + normalizeToken(sourceConclusion) !== "requested" || + currentRound !== 1 + ) { + return; + } + createOrchestrateStopComment(decision); +} + +function commentOnPlannerClarificationStop(decision: HandoffDecision): void { + if (!formatPlannerClarificationComment(decision) && !formatPlannerAnswerComment(decision)) { + return; + } + createOrchestrateStopComment(decision); +} + +function commentOnDelegationFailure(decision: HandoffDecision): void { + if (normalizeToken(sourceAction) !== "orchestrate") { + return; + } + createOrchestrateStopComment(decision); +} + +function commentOnUnsatisfactoryActionStop(decision: HandoffDecision): void { + if (formatPlannerClarificationComment(decision)) { + return; + } + const normalizedSourceAction = normalizeToken(sourceAction); + if (normalizedSourceAction !== "implement" && normalizedSourceAction !== "fix_pr") { + return; + } + if (!UNSATISFACTORY_ACTION_CONCLUSIONS.has(normalizeToken(sourceConclusion))) { + return; + } + createOrchestrateStopComment(decision); +} + +function commentOnTerminalMetaOrchestratorStop(decision: HandoffDecision): void { + if (decision.decision !== "stop") { + return; + } + if (formatPlannerClarificationComment(decision) || formatPlannerAnswerComment(decision)) { + return; + } + if ( + normalizeToken(sourceAction) !== "orchestrate" || + automationMode !== "agent" || + normalizeToken(sourceTargetKind) !== "issue" + ) { + return; + } + if (currentRound === 1 && normalizeToken(sourceConclusion) === "requested") { + return; + } + createOrchestrateStopComment(decision); +} + +function decideManualOrchestration(): HandoffDecision { + const nextRound = currentRound + 1; + if (currentRound >= maxRounds) { + return { decision: "stop", reason: "automation round budget exhausted", nextRound }; + } + + const normalizedKind = normalizeToken(sourceTargetKind); + if (normalizedKind === "issue") { + return { + decision: "dispatch", + nextAction: "implement", + targetNumber, + reason: "manual orchestrate start on issue; dispatching implement", + nextRound, + }; + } + + if (normalizedKind === "pull_request") { + const status = readPrStatus(repo, targetNumber); + if (!status) { + return { decision: "stop", reason: "could not read pull request status", nextRound }; + } + if (status.state !== "OPEN") { + return { decision: "stop", reason: `pull request is ${status.state.toLowerCase()}`, nextRound }; + } + if (status.reviewDecision === "CHANGES_REQUESTED") { + return { + decision: "dispatch", + nextAction: "fix-pr", + targetNumber, + reason: "manual orchestrate start on PR with CHANGES_REQUESTED; dispatching fix-pr", + nextRound, + }; + } + return { + decision: "dispatch", + nextAction: "review", + targetNumber, + reason: "manual orchestrate start on PR; dispatching review", + nextRound, + }; + } + + return { decision: "stop", reason: `unsupported target kind ${sourceTargetKind || "missing"}`, nextRound }; +} + +function decidePlannerOrchestration(): HandoffDecision { + const nextRound = currentRound + 1; + const normalizedKind = normalizeToken(sourceTargetKind); + if (normalizedKind === "pull_request") { + const status = readPrStatus(repo, targetNumber); + if (!status) { + return { decision: "stop", reason: "could not read pull request status", nextRound }; + } + if (status.state !== "OPEN") { + return { decision: "stop", reason: `pull request is ${status.state.toLowerCase()}`, nextRound }; + } + } + return decideHandoff({ + automationMode, + sourceAction, + sourceConclusion, + sourceRecommendedNextStep, + targetKind: sourceTargetKind, + targetNumber, + nextTargetNumber: process.env.NEXT_TARGET_NUMBER || "", + currentRound, + maxRounds, + allowSelfApprove, + allowSelfMerge, + sourceHandoffContext, + plannerDecision: readPlannerDecision(), + }); +} + +function validateInitialOrchestrateCapabilities(): HandoffDecision | null { + const reason = initialOrchestrateCapabilityStopReason({ + sourceAction, + sourceConclusion, + currentRound, + allowSelfApprove, + allowSelfMerge, + authorAssociation: sourceAssociationRaw, + accessPolicy: accessPolicyRaw, + isPublicRepo, + }); + return reason ? { decision: "stop", reason, nextRound: currentRound + 1 } : null; +} + +const authorizationStop = validateInitialOrchestrateCapabilities(); +const routeDecision = authorizationStop || (normalizeToken(sourceAction) === "orchestrate" + ? automationMode === "agent" && + ["issue", "pull_request"].includes(normalizeToken(sourceTargetKind)) + ? decidePlannerOrchestration() + : decideManualOrchestration() + : decideHandoff({ + automationMode, + sourceAction, + sourceConclusion, + sourceRecommendedNextStep, + targetKind: sourceTargetKind, + targetNumber, + nextTargetNumber: process.env.NEXT_TARGET_NUMBER || "", + currentRound, + maxRounds, + allowSelfApprove, + allowSelfMerge, + sourceHandoffContext, + plannerDecision: automationMode === "agent" ? readPlannerDecision() : null, + })); +const decision = routeDecision; + +if (decision.decision === "dispatch" && decision.nextAction === "fix-pr" && !decision.handoffContext) { + decision.handoffContext = fallbackFixPrHandoffContext(); +} + +setOutput("decision", decision.decision); +setOutput("next_action", decision.decision === "delegate_issue" ? "delegate_issue" : decision.nextAction || ""); +setOutput("target_number", decision.targetNumber || ""); +setOutput("reason", decision.reason); +setOutput("next_round", String(decision.nextRound)); +setOutput("handoff_context", decision.handoffContext || ""); +setOutput("deduped", "false"); +setOutput("dedupe_key", ""); +setOutput("marker_comment_id", ""); + +if (decision.decision !== "dispatch" && decision.decision !== "delegate_issue") { + console.log(`Handoff ${decision.decision}: ${decision.reason}`); + try { + commentOnPlannerClarificationStop(decision); + commentOnInitialOrchestrateStop(decision); + commentOnUnsatisfactoryActionStop(decision); + reportTerminalToParent(decision); + commentOnTerminalMetaOrchestratorStop(decision); + } catch (err: unknown) { + console.warn(`Failed to report terminal sub-orchestration state: ${errorText(err)}`); + } + process.exit(0); +} + +if (!repo || !ref || (!decision.nextAction && decision.decision !== "delegate_issue") || !decision.targetNumber) { + console.error("Missing required dispatch context for handoff"); + process.exit(2); +} + +let dispatchTargetNumber = decision.targetNumber; +const dispatchName = decision.decision === "delegate_issue" ? "delegate_issue" : decision.nextAction || ""; +if (decision.decision === "delegate_issue") { + try { + dispatchTargetNumber = ensureSubOrchestrationIssue(decision); + decision.targetNumber = dispatchTargetNumber; + setOutput("target_number", dispatchTargetNumber); + } catch (err: unknown) { + const message = `child issue delegation failed: ${errorText(err).slice(0, 1000)}`; + const stopDecision: HandoffDecision = { + decision: "stop", + reason: message, + nextRound: decision.nextRound, + targetNumber, + }; + setOutput("decision", "stop"); + setOutput("next_action", ""); + setOutput("target_number", targetNumber); + setOutput("reason", message); + console.error(message); + try { + commentOnDelegationFailure(stopDecision); + } catch (commentErr: unknown) { + console.warn(`Failed to report child issue delegation failure: ${errorText(commentErr)}`); + } + process.exit(0); + } +} + +const { baseBranch: effectiveBaseBranch, basePr: effectiveBasePr } = resolveEffectiveBaseInputs(decision); +if (decision.nextAction === "implement" && effectiveBaseBranch && effectiveBasePr) { + const message = "set only one of base_branch or base_pr for implementation"; + const stopDecision: HandoffDecision = { + decision: "stop", + reason: message, + nextRound: decision.nextRound, + targetNumber: decision.targetNumber, + }; + setOutput("decision", "stop"); + setOutput("next_action", ""); + setOutput("target_number", decision.targetNumber || ""); + setOutput("reason", message); + console.error(message); + try { + commentOnInitialOrchestrateStop(stopDecision); + } catch (err: unknown) { + console.warn(`Failed to report implementation base input conflict: ${errorText(err)}`); + } + process.exit(0); +} + +const dedupeKey = buildHandoffDedupeKey({ + repo, + sourceRunId, + sourceAction, + sourceTargetNumber: targetNumber, + nextAction: dispatchName, + nextTargetNumber: dispatchTargetNumber, + nextRound: decision.nextRound, +}); +setOutput("dedupe_key", dedupeKey); + +const markerTargetNumber = parsePositiveTargetNumber(dispatchTargetNumber); +if (!markerTargetNumber) { + console.error(`Invalid handoff marker target number: ${decision.targetNumber}`); + process.exit(2); +} + +const existingMarkers = findHandoffMarkers(repo, markerTargetNumber, dedupeKey); +const nowMs = Date.now(); +const activeMarker = existingMarkers.find((marker) => ( + marker.state === "dispatched" || + (marker.state === "pending" && !isPendingHandoffMarkerStale(marker, nowMs, PENDING_MARKER_TTL_MS)) +)); +if (activeMarker) { + setOutput("deduped", "true"); + setOutput("marker_comment_id", activeMarker.id); + console.log(`Skipping duplicate handoff ${dedupeKey} (${activeMarker.state})`); + process.exit(0); +} + +for (const staleMarker of existingMarkers.filter((marker) => + isPendingHandoffMarkerStale(marker, nowMs, PENDING_MARKER_TTL_MS) +)) { + try { + updateIssueComment(repo, staleMarker.id, formatHandoffMarkerComment({ + key: dedupeKey, + state: "failed", + sourceAction, + nextAction: dispatchName, + targetKind: decision.nextAction === "implement" || decision.decision === "delegate_issue" ? "issue" : "pull_request", + targetNumber: dispatchTargetNumber, + nextRound: decision.nextRound, + maxRounds, + reason: decision.reason, + handoffContext: decision.handoffContext, + error: "Pending handoff marker expired before dispatch completed; retrying handoff.", + })); + } catch (err: unknown) { + console.warn(`Failed to expire stale pending handoff marker ${staleMarker.id}: ${errorText(err)}`); + } +} + +const pendingBody = formatHandoffMarkerComment({ + key: dedupeKey, + state: "pending", + sourceAction, + nextAction: dispatchName, + targetKind: decision.nextAction === "implement" || decision.decision === "delegate_issue" ? "issue" : "pull_request", + targetNumber: dispatchTargetNumber, + nextRound: decision.nextRound, + maxRounds, + reason: decision.reason, + handoffContext: decision.handoffContext, + createdAtMs: nowMs, +}); +const markerCommentId = createIssueComment(repo, markerTargetNumber, pendingBody); +setOutput("marker_comment_id", markerCommentId); + +const commonInputs = { + requested_by: requestedBy, + request_text: requestText, + orchestration_enabled: "true", + automation_mode: automationMode === "disabled" ? "heuristics" : automationMode, + automation_current_round: String(decision.nextRound), + automation_max_rounds: String(maxRounds), + session_bundle_mode: sessionBundleMode, +}; + +try { + if (decision.nextAction === "review") { + dispatchWorkflow(repo, "agent-review.yml", ref, { + ...commonInputs, + pr_number: decision.targetNumber, + }); + } else if (decision.nextAction === "agent-self-approve") { + dispatchWorkflow(repo, "agent-self-approve.yml", ref, { + ...commonInputs, + pr_number: decision.targetNumber, + source_conclusion: sourceConclusion, + source_recommended_next_step: sourceRecommendedNextStep, + }); + } else if (decision.nextAction === "agent-self-merge") { + dispatchWorkflow(repo, "agent-self-merge.yml", ref, { + ...commonInputs, + pr_number: decision.targetNumber, + }); + } else if (decision.nextAction === "implement") { + dispatchWorkflow(repo, "agent-implement.yml", ref, { + ...commonInputs, + issue_number: decision.targetNumber, + approval_comment_url: "", + base_branch: effectiveBaseBranch, + base_pr: effectiveBasePr, + implementation_route: "implement", + implementation_prompt: "implement", + }); + } else if (decision.nextAction === "fix-pr") { + dispatchWorkflow(repo, "agent-fix-pr.yml", ref, { + ...commonInputs, + pr_number: decision.targetNumber, + request_source_kind: "workflow_dispatch", + orchestrator_context: decision.handoffContext || "", + }); + } else if (decision.decision === "delegate_issue") { + dispatchWorkflow(repo, "agent-orchestrator.yml", ref, { + requested_by: requestedBy, + request_text: requestText, + automation_max_rounds: String(maxRounds), + session_bundle_mode: sessionBundleMode, + source_action: "orchestrate", + source_conclusion: "delegated", + source_run_id: sourceRunId, + target_kind: "issue", + target_number: dispatchTargetNumber, + automation_mode: "heuristics", + automation_current_round: "1", + base_branch: effectiveBaseBranch, + base_pr: effectiveBasePr, + }); + } else { + console.error(`Unsupported next action: ${decision.nextAction}`); + process.exit(2); + } +} catch (err: unknown) { + const message = errorText(err).slice(0, 1000); + try { + updateIssueComment(repo, markerCommentId, formatHandoffMarkerComment({ + key: dedupeKey, + state: "failed", + sourceAction, + nextAction: dispatchName, + targetKind: decision.nextAction === "implement" || decision.decision === "delegate_issue" ? "issue" : "pull_request", + targetNumber: dispatchTargetNumber, + nextRound: decision.nextRound, + maxRounds, + reason: decision.reason, + handoffContext: decision.handoffContext, + error: message, + })); + } catch (updateErr: unknown) { + console.warn(`Failed to mark handoff ${dedupeKey} as failed: ${errorText(updateErr)}`); + } + throw err; +} + +const dispatchedBody = formatHandoffMarkerComment({ + key: dedupeKey, + state: "dispatched", + sourceAction, + nextAction: dispatchName, + targetKind: decision.nextAction === "implement" || decision.decision === "delegate_issue" ? "issue" : "pull_request", + targetNumber: dispatchTargetNumber, + nextRound: decision.nextRound, + maxRounds, + reason: decision.reason, + handoffContext: decision.handoffContext, + createdAtMs: nowMs, +}); + +try { + updateIssueComment(repo, markerCommentId, dispatchedBody); +} catch (err: unknown) { + console.warn(`Handoff dispatched but marker ${markerCommentId} remained pending: ${errorText(err)}`); +} + +if (collapseOldReviews) { + try { + const collapsed = collapsePreviousHandoffComments({ + repo, + targetNumber: markerTargetNumber, + targetKind: decision.nextAction === "implement" || decision.decision === "delegate_issue" ? "issue" : "pull_request", + excludeCommentId: markerCommentId, + currentCreatedAtMs: nowMs, + }); + if (collapsed > 0) { + console.log(`Collapsed ${collapsed} previous orchestrator handoff comment(s).`); + } + } catch (err: unknown) { + console.warn( + `Failed to collapse previous orchestrator handoff comments for ${repo}#${markerTargetNumber}: ${errorText(err)}`, + ); + } +} + +console.log(`Handoff dispatched ${dispatchName} for #${decision.targetNumber}: ${decision.reason}`); diff --git a/.agent/src/cli/orchestrator-preflight.ts b/.agent/src/cli/orchestrator-preflight.ts new file mode 100644 index 0000000..22b2cb2 --- /dev/null +++ b/.agent/src/cli/orchestrator-preflight.ts @@ -0,0 +1,55 @@ +// CLI: compute cheap preflight outputs for agent-orchestrator.yml. +// Env: AUTOMATION_MODE, AUTOMATION_CURRENT_ROUND, AUTOMATION_MAX_ROUNDS, +// SOURCE_ACTION, SOURCE_CONCLUSION, TARGET_KIND, AUTHOR_ASSOCIATION, +// ACCESS_POLICY, REPOSITORY_PRIVATE, AGENT_ALLOW_SELF_APPROVE, +// AGENT_ALLOW_SELF_MERGE +// Outputs: automation_mode, current_round, max_rounds, planner_enabled, +// authorization_stop, authorization_stop_reason +// The authorization_stop outputs are diagnostic; planner_enabled is the workflow gate, +// and orchestrate-handoff posts the parent-visible stop comment. + +import { normalizeAutomationMode } from "../handoff.js"; +import { initialOrchestrateCapabilityStopReason } from "../orchestrator-capabilities.js"; +import { setOutput } from "../output.js"; + +function positiveInt(value: string, fallback: number): number { + const parsed = Number.parseInt(value, 10); + return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; +} + +function envFlagEnabled(value: string): boolean { + return ["true", "1", "yes", "on"].includes(String(value || "").trim().toLowerCase()); +} + +const automationMode = normalizeAutomationMode(process.env.AUTOMATION_MODE || "disabled"); +const currentRound = positiveInt(process.env.AUTOMATION_CURRENT_ROUND || "", 1); +const maxRounds = positiveInt(process.env.AUTOMATION_MAX_ROUNDS || "", 12); +const sourceAction = String(process.env.SOURCE_ACTION || "").trim().toLowerCase(); +const sourceConclusion = String(process.env.SOURCE_CONCLUSION || "unknown").trim().toLowerCase(); +const targetKind = String(process.env.TARGET_KIND || "").trim().toLowerCase(); +const authorizationStopReason = initialOrchestrateCapabilityStopReason({ + sourceAction, + sourceConclusion, + currentRound, + allowSelfApprove: envFlagEnabled(process.env.AGENT_ALLOW_SELF_APPROVE || ""), + allowSelfMerge: envFlagEnabled(process.env.AGENT_ALLOW_SELF_MERGE || ""), + authorAssociation: process.env.AUTHOR_ASSOCIATION || "", + accessPolicy: process.env.ACCESS_POLICY || "", + isPublicRepo: String(process.env.REPOSITORY_PRIVATE || "").trim().toLowerCase() === "false", +}); +const initialOrchestrate = sourceAction === "orchestrate"; +const plannerEnabled = !authorizationStopReason && + automationMode === "agent" && + currentRound < maxRounds && + (!initialOrchestrate || targetKind === "issue" || targetKind === "pull_request"); + +setOutput("automation_mode", automationMode); +setOutput("current_round", String(currentRound)); +setOutput("max_rounds", String(maxRounds)); +setOutput("planner_enabled", String(plannerEnabled)); +setOutput("authorization_stop", String(Boolean(authorizationStopReason))); +setOutput("authorization_stop_reason", authorizationStopReason); + +console.log( + `Orchestrator preflight: mode=${automationMode}, source_action=${sourceAction || "missing"}, target_kind=${targetKind || "missing"}, round=${currentRound}/${maxRounds}, planner_enabled=${plannerEnabled}, authorization_stop=${Boolean(authorizationStopReason)}`, +); diff --git a/.agent/src/cli/parse-response.ts b/.agent/src/cli/parse-response.ts new file mode 100644 index 0000000..f4e19b9 --- /dev/null +++ b/.agent/src/cli/parse-response.ts @@ -0,0 +1,31 @@ +// CLI: parse agent response and determine run status. +// Usage: node .agent/dist/cli/parse-response.js +// Env: RESPONSE_FILE, AGENT_EXIT_CODE, HAS_CHANGES, VERIFY_EXIT_CODE, HEAD_CHANGED +// Outputs: status, summary, commit_message, pr_title, pr_body + +import { readFileSync } from "node:fs"; +import { + determineRunStatus, + normalizeImplementationResponse, +} from "../response.js"; +import { setOutput } from "../output.js"; + +const agentExit = Number(process.env.AGENT_EXIT_CODE || "0"); +const hasChanges = process.env.HAS_CHANGES === "true"; +const headChanged = process.env.HEAD_CHANGED === "true"; +const verifyExit = Number(process.env.VERIFY_EXIT_CODE || "0"); +const responseFile = process.env.RESPONSE_FILE || ""; + +const status = determineRunStatus(agentExit, hasChanges, verifyExit, headChanged); +setOutput("status", status); + +let raw = ""; +if (responseFile) { + try { raw = readFileSync(responseFile, "utf8"); } catch { /* ok */ } +} + +const response = normalizeImplementationResponse(raw); +setOutput("summary", response.summary); +setOutput("commit_message", response.commitMessage); +setOutput("pr_title", response.prTitle); +setOutput("pr_body", response.prBody); diff --git a/.agent/src/cli/post-comment.ts b/.agent/src/cli/post-comment.ts new file mode 100644 index 0000000..7a43699 --- /dev/null +++ b/.agent/src/cli/post-comment.ts @@ -0,0 +1,129 @@ +// CLI: post a status comment to an issue or PR. +// Usage: node .agent/dist/cli/post-comment.js +// Env: COMMENT_TARGET (issue or pr), TARGET_NUMBER, ROUTE, STATUS, +// RESPONSE_FILE (optional), BRANCH, PR_URL, REQUESTED_BY, +// APPROVAL_COMMENT_URL, AGENT_COLLAPSE_OLD_REVIEWS +// Outputs: status + +import { readFileSync } from "node:fs"; +import { fetchPrMeta, postIssueComment, postPrComment } from "../github.js"; +import { + collapsePreviousFixPrComments, + collapsePreviousReviewSummaries, +} from "../review-summary-minimize.js"; +import { + formatImplementComment, + formatFixPrComment, + formatReviewComment, + normalizeImplementationResponse, + summaryFromAgentResponse, + type RunStatus, +} from "../response.js"; +import { setOutput } from "../output.js"; +import { formatSessionRestoreNotice } from "../session-bundle.js"; + +const target = process.env.COMMENT_TARGET || "issue"; // "issue" or "pr" +const targetNumber = Number(process.env.TARGET_NUMBER || process.env.ISSUE_NUMBER || process.env.PR_NUMBER); +const route = process.env.ROUTE || "implement"; +const status = (process.env.STATUS || "failed") as RunStatus; +const responseFile = process.env.RESPONSE_FILE || ""; +const branch = process.env.BRANCH || ""; +const prUrl = process.env.PR_URL || ""; +const requestedBy = process.env.REQUESTED_BY || ""; +const approvalCommentUrl = process.env.APPROVAL_COMMENT_URL || ""; +const resumeStatus = process.env.RESUME_STATUS || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; +const collapseOldReviews = !["false", "0", "no", "off"].includes( + (process.env.AGENT_COLLAPSE_OLD_REVIEWS || "").trim().toLowerCase(), +); + +let rawResponse = ""; +if (responseFile) { + try { rawResponse = readFileSync(responseFile, "utf8"); } catch { /* ok */ } +} +const summary = summaryFromAgentResponse(route, rawResponse); + +let body: string; + +if (route === "review") { + let reviewedHeadSha = ""; + const capturedReviewedHeadSha = String(process.env.REVIEWED_HEAD_SHA || "").trim(); + if (capturedReviewedHeadSha && target === "pr" && repo && targetNumber > 0) { + try { + const currentHeadSha = fetchPrMeta(targetNumber, repo).headOid; + if (currentHeadSha === capturedReviewedHeadSha) { + reviewedHeadSha = capturedReviewedHeadSha; + } else { + console.warn("Review synthesis head marker omitted because the PR head changed during review."); + } + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.warn(`Review synthesis head marker omitted because PR metadata could not be read: ${message}`); + } + } + body = formatReviewComment({ + synthesisBody: summary, + requestedBy: requestedBy || undefined, + approvalCommentUrl: approvalCommentUrl || undefined, + reviewedHeadSha: reviewedHeadSha || undefined, + }); +} else if (route === "fix-pr") { + body = formatFixPrComment({ + status, + summary, + branch, + requestedBy: requestedBy || undefined, + approvalCommentUrl: approvalCommentUrl || undefined, + }); +} else { + // implement or other + const parsed = route === "implement" + ? normalizeImplementationResponse(rawResponse) + : { summary, prTitle: "", prBody: "" }; + body = formatImplementComment({ + status, + summary: parsed.summary, + branch: branch || undefined, + prUrl: prUrl || undefined, + approvalCommentUrl: approvalCommentUrl || undefined, + }); +} + +const continuityNote = formatSessionRestoreNotice({ resumeStatus, runStatus: status }); +if (continuityNote) { + body = `> ${continuityNote}\n\n${body}`; +} + +if (target === "pr") { + if (route === "review" && collapseOldReviews) { + try { + const collapsed = collapsePreviousReviewSummaries({ repo, prNumber: targetNumber }); + if (collapsed > 0) { + console.log(`Collapsed ${collapsed} previous AI review synthesis comment(s).`); + } + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.warn( + `Failed to collapse previous AI review synthesis comments for ${repo}#${targetNumber}: ${message}`, + ); + } + } + if (route === "fix-pr" && collapseOldReviews) { + try { + const collapsed = collapsePreviousFixPrComments({ repo, prNumber: targetNumber }); + if (collapsed > 0) { + console.log(`Collapsed ${collapsed} previous fix-pr status comment(s).`); + } + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.warn( + `Failed to collapse previous fix-pr status comments for ${repo}#${targetNumber}: ${message}`, + ); + } + } + postPrComment(targetNumber, body); +} else { + postIssueComment(targetNumber, body); +} + +setOutput("comment_posted", "true"); diff --git a/.agent/src/cli/post-project-management-summary.ts b/.agent/src/cli/post-project-management-summary.ts new file mode 100644 index 0000000..f1b84dd --- /dev/null +++ b/.agent/src/cli/post-project-management-summary.ts @@ -0,0 +1,99 @@ +#!/usr/bin/env node +// CLI: publish the project-manager agent's final summary. +// Env: BODY or BODY_FILE, GITHUB_STEP_SUMMARY, GITHUB_REPOSITORY, +// AGENT_PROJECT_MANAGEMENT_POST_SUMMARY, +// AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY, +// AGENT_PROJECT_MANAGEMENT_SUMMARY_DATE (optional) + +import { appendFileSync, existsSync, readFileSync } from "node:fs"; +import { addDiscussionComment, findRepositoryDiscussionByTitle } from "../discussion.js"; +import { setOutput } from "../output.js"; + +function boolEnv(name: string, fallback = false): boolean { + const value = (process.env[name] || "").trim().toLowerCase(); + if (!value) return fallback; + return ["1", "true", "yes", "on"].includes(value); +} + +function requiredEnv(name: string): string { + const value = process.env[name]?.trim() || ""; + if (!value) throw new Error(`${name} is required`); + return value; +} + +function parseRepoSlug(slug: string): { owner: string; repo: string } { + const [owner, repo, extra] = slug.split("/"); + if (!owner || !repo || extra) { + throw new Error(`GITHUB_REPOSITORY must be owner/repo (got: ${slug || "missing"})`); + } + return { owner, repo }; +} + +function dailySummaryTitle(date = new Date()): string { + const override = process.env.AGENT_PROJECT_MANAGEMENT_SUMMARY_DATE?.trim(); + if (override) return `Daily Summary — ${override}`; + return `Daily Summary — ${date.toISOString().slice(0, 10)}`; +} + +function writeStepSummary(markdown: string): void { + const summaryFile = process.env.GITHUB_STEP_SUMMARY; + if (!summaryFile) return; + appendFileSync(summaryFile, `${markdown}\n`); +} + +function readSummary(): string { + const body = process.env.BODY?.trim(); + if (body) return body; + + const bodyFile = requiredEnv("BODY_FILE"); + if (!existsSync(bodyFile)) { + throw new Error(`Project management summary file was not produced: ${bodyFile}`); + } + + return readFileSync(bodyFile, "utf8").trim(); +} + +function publishDiscussionComment(summary: string): string | null { + const { owner, repo } = parseRepoSlug(requiredEnv("GITHUB_REPOSITORY")); + const category = process.env.AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY?.trim() || "General"; + const title = dailySummaryTitle(); + const discussion = findRepositoryDiscussionByTitle(owner, repo, title, category); + + if (!discussion) { + console.warn(`Daily summary discussion '${title}' was not found in category '${category}'; skipping comment.`); + return null; + } + + const url = addDiscussionComment(discussion.id, summary); + console.log(`Posted project management summary to ${discussion.url || `discussion #${discussion.number}`}: ${url}`); + return url; +} + +function main(): number { + try { + const summary = readSummary(); + if (!summary) { + throw new Error("Project management summary is empty"); + } + + writeStepSummary(summary); + setOutput("summary", summary); + + if (!boolEnv("AGENT_PROJECT_MANAGEMENT_POST_SUMMARY")) { + setOutput("summary_posted", "false"); + setOutput("summary_url", ""); + console.log("Project management summary posting is disabled; wrote Actions step summary only."); + return 0; + } + + const url = publishDiscussionComment(summary); + setOutput("summary_posted", url ? "true" : "false"); + setOutput("summary_url", url || ""); + return 0; + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } +} + +process.exitCode = main(); diff --git a/.agent/src/cli/post-response.ts b/.agent/src/cli/post-response.ts new file mode 100644 index 0000000..53848e4 --- /dev/null +++ b/.agent/src/cli/post-response.ts @@ -0,0 +1,103 @@ +// CLI: post a response to the correct GitHub surface. +// Usage: node .agent/dist/cli/post-response.js +// Env: BODY_FILE, RESPONSE_KIND, TARGET_NUMBER, REVIEW_COMMENT_ID, +// DISCUSSION_ID, REPLY_TO_ID, GITHUB_REPOSITORY, +// AGENT_COLLAPSE_OLD_REVIEWS + +import { readFileSync } from "node:fs"; +import { upsertPrCommentByMarker } from "../github.js"; +import { postResponse } from "../respond.js"; +import { + collapsePreviousRubricsReviews, + isRubricsReviewBody, +} from "../review-summary-minimize.js"; +import { SELF_APPROVAL_STATUS_MARKER } from "../self-approval.js"; +import { SELF_MERGE_STATUS_MARKER } from "../self-merge.js"; +import { formatSessionRestoreNotice } from "../session-bundle.js"; + +const bodyFile = process.env.BODY_FILE || ""; +const responseKind = process.env.RESPONSE_KIND || "issue_comment"; +const targetNumber = Number(process.env.TARGET_NUMBER || "0"); +const reviewCommentId = Number(process.env.REVIEW_COMMENT_ID || "0") || undefined; +const discussionNodeId = process.env.DISCUSSION_ID || undefined; +const replyToId = process.env.REPLY_TO_ID || undefined; +const repo = process.env.GITHUB_REPOSITORY || undefined; +const resumeStatus = process.env.RESUME_STATUS || ""; +const runStatus = process.env.STATUS || "success"; +const collapseOldReviews = !["false", "0", "no", "off"].includes( + (process.env.AGENT_COLLAPSE_OLD_REVIEWS || "").trim().toLowerCase(), +); + +let body = ""; +if (bodyFile) { + try { + body = readFileSync(bodyFile, "utf8"); + } catch { + console.error(`Could not read body file: ${bodyFile}`); + } +} + +if (!body.trim()) { + body = "I was unable to produce a response. Please check the workflow logs."; +} + +const continuityNote = formatSessionRestoreNotice({ resumeStatus, runStatus }); +if (continuityNote) { + body = `> ${continuityNote}\n\n${body}`; +} + +let posted = false; +let markerUpsertFailed = false; +const markerUpsert = body.includes(SELF_APPROVAL_STATUS_MARKER) + ? { marker: SELF_APPROVAL_STATUS_MARKER, label: "self-approval" } + : body.includes(SELF_MERGE_STATUS_MARKER) + ? { marker: SELF_MERGE_STATUS_MARKER, label: "self-merge" } + : null; +if ( + responseKind === "pr_comment" && + repo && + targetNumber > 0 && + markerUpsert +) { + try { + const action = upsertPrCommentByMarker(targetNumber, repo, markerUpsert.marker, body); + console.log(`${action === "updated" ? "Updated" : "Created"} ${markerUpsert.label} status comment.`); + posted = true; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.error( + `Failed to upsert ${markerUpsert.label} status comment for ${repo}#${targetNumber}: ${message}`, + ); + markerUpsertFailed = true; + process.exitCode = 1; + } +} + +if ( + !posted && + !markerUpsertFailed && + responseKind === "pr_comment" && + repo && + targetNumber > 0 && + collapseOldReviews && + isRubricsReviewBody(body) +) { + try { + const collapsed = collapsePreviousRubricsReviews({ repo, prNumber: targetNumber }); + if (collapsed > 0) { + console.log(`Collapsed ${collapsed} previous rubrics review comment(s).`); + } + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.warn( + `Failed to collapse previous rubrics review comments for ${repo}#${targetNumber}: ${message}`, + ); + } +} + +if (!posted && !markerUpsertFailed) { + postResponse( + { responseKind, targetNumber, reviewCommentId, discussionNodeId, replyToId, repo }, + body, + ); +} diff --git a/.agent/src/cli/prepare-approval.ts b/.agent/src/cli/prepare-approval.ts new file mode 100644 index 0000000..3cadaec --- /dev/null +++ b/.agent/src/cli/prepare-approval.ts @@ -0,0 +1,88 @@ +// CLI: build and write the approval request comment body. +// Usage: node .agent/dist/cli/prepare-approval.js +// Env: ROUTE, SOURCE_KIND, TARGET_KIND, TARGET_NUMBER, TARGET_URL, +// SUMMARY, ISSUE_TITLE, ISSUE_BODY, REQUEST_TEXT, WORKFLOW_FILE +// Outputs: body_file + +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { randomBytes } from "node:crypto"; +import { setOutput } from "../output.js"; +import { buildApprovalRequestMarker } from "../approval.js"; +import { DEFAULT_MENTION } from "../context.js"; + +const route = process.env.ROUTE || "implement"; +const sourceKind = process.env.SOURCE_KIND || ""; +const targetKind = process.env.TARGET_KIND || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || "0"); +const targetUrl = process.env.TARGET_URL || ""; +const summary = process.env.SUMMARY || ""; +const issueTitle = process.env.ISSUE_TITLE || ""; +const issueBody = process.env.ISSUE_BODY || ""; +const requestText = process.env.REQUEST_TEXT || ""; +const workflowFile = process.env.WORKFLOW_FILE || "agent-implement.yml"; +const mention = process.env.INPUT_MENTION || DEFAULT_MENTION; +const requestId = `req-${randomBytes(3).toString("hex")}`; + +const routeLabel = route === "create-action" ? "action creation" : "implementation"; + +// Build the hidden marker with dispatch metadata +const markerData: Record = { + route, + source_kind: sourceKind, + target_kind: targetKind, + target_number: targetNumber, + target_url: targetUrl, + workflow: workflowFile, + request_id: requestId, + request_text: requestText, +}; +if (issueTitle) { + markerData.issue_title = issueTitle; + markerData.issue_body = issueBody; +} +const marker = buildApprovalRequestMarker(markerData); + +// Build the comment body +const lines: string[] = []; +lines.push(`I triaged this as a \`${route}\` request.`); +lines.push(""); +lines.push(summary); +lines.push(""); + +if ((route === "implement" || route === "create-action") && issueTitle && targetKind !== "issue") { + lines.push("### Proposed issue"); + lines.push(""); + lines.push(`> **${issueTitle}**`); + lines.push(">"); + for (const line of issueBody.split("\n")) { + lines.push(`> ${line}`); + } + lines.push(""); + lines.push("Reply with:"); + lines.push(""); + lines.push("```text"); + lines.push(`${mention} /approve ${requestId}`); + lines.push("```"); + lines.push(""); + lines.push(`to create the issue and start the ${routeLabel} workflow.`); +} else { + lines.push("Reply with:"); + lines.push(""); + lines.push("```text"); + lines.push(`${mention} /approve ${requestId}`); + lines.push("```"); + lines.push(""); + lines.push(`to start the ${routeLabel} workflow.`); +} + +lines.push(""); +lines.push(marker); + +const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; +const bodyFile = join( + runnerTemp, + `agent-approval-request-${randomBytes(8).toString("hex")}.md`, +); +writeFileSync(bodyFile, lines.join("\n") + "\n", "utf8"); +setOutput("body_file", bodyFile); diff --git a/.agent/src/cli/prepare-release.ts b/.agent/src/cli/prepare-release.ts new file mode 100644 index 0000000..5e5c3b8 --- /dev/null +++ b/.agent/src/cli/prepare-release.ts @@ -0,0 +1,109 @@ +// CLI: create or reuse the tracking issue for a manual release prepare run. +// Usage: node .agent/dist/cli/prepare-release.js +// Env: GITHUB_REPOSITORY, VERSION, REQUESTED_BY, RUNNER_TEMP +// Outputs: issue_number, issue_url, request_text, version + +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { randomBytes } from "node:crypto"; +import { createIssue, gh } from "../github.js"; +import { setOutput } from "../output.js"; +import { parseReleaseVersion } from "../release-version.js"; + +interface ListedIssue { + number?: number; + title?: string; + url?: string; +} + +function normalizeVersion(raw: string): string { + const value = raw.trim(); + return value ? parseReleaseVersion(value).version : ""; +} + +function issueTitle(version: string): string { + return version ? `Prepare Sepo release ${version}` : "Prepare next Sepo release"; +} + +function issueBody(version: string, requestedBy: string): string { + const request = version + ? `Prepare the Sepo ${version} release pull request.` + : "Determine and prepare the next Sepo release pull request."; + return [ + "## Goal", + request, + "", + "## Acceptance criteria", + "- Keep `.agent/package.json` as the canonical Sepo package/runtime version.", + "- Validate the release version against `.agent/docs/technical-details/versioning.md`.", + "- Update `.agent/package-lock.json` if package metadata changes require it.", + "- Update `.agent/CHANGELOG.md` with release notes for the version.", + "- Update docs or checklist content changed by this release.", + "- Open a pull request.", + "- Do not create git tags, GitHub Releases, or package publications.", + "", + `Requested by: ${requestedBy || "workflow_dispatch"}`, + "", + ``, + ].join("\n"); +} + +function requestText(version: string): string { + return version + ? `Prepare the Sepo ${version} release pull request.` + : "Determine and prepare the next Sepo release pull request."; +} + +function findOpenIssue(repo: string, title: string): ListedIssue | null { + const raw = gh([ + "issue", + "list", + "--repo", + repo, + "--state", + "open", + "--search", + title, + "--json", + "number,title,url", + ]); + const issues = JSON.parse(raw) as ListedIssue[]; + return issues.find((issue) => issue.title === title && issue.number && issue.url) || null; +} + +function createReleaseIssue(repo: string, title: string, version: string, requestedBy: string): ListedIssue | null { + const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; + const bodyFile = join(runnerTemp, `release-prepare-${randomBytes(8).toString("hex")}.md`); + writeFileSync(bodyFile, issueBody(version, requestedBy) + "\n", "utf8"); + const url = createIssue({ title, bodyFile, repo }); + const numberMatch = url.match(/\/issues\/(\d+)$/); + if (!numberMatch) { + console.error(`Could not parse created release prepare issue number from URL: ${url || "(empty)"}`); + process.exitCode = 1; + return null; + } + return { number: Number.parseInt(numberMatch[1], 10), title, url }; +} + +const repo = process.env.GITHUB_REPOSITORY || ""; +const requestedBy = process.env.REQUESTED_BY || ""; +const version = normalizeVersion(process.env.VERSION || ""); + +if (!repo) { + console.error("Missing required env: GITHUB_REPOSITORY"); + process.exitCode = 2; +} else { + const title = issueTitle(version); + const existing = findOpenIssue(repo, title); + const issue = existing || createReleaseIssue(repo, title, version, requestedBy); + + if (issue) { + setOutput("issue_number", String(issue.number || "")); + setOutput("issue_url", issue.url || ""); + setOutput("issue_action", existing ? "reused" : "created"); + setOutput("request_text", requestText(version)); + setOutput("version", version); + + console.log(`${existing ? "Reused" : "Created"} release prepare issue: ${issue.url}`); + } +} diff --git a/.agent/src/cli/prepare-rubrics-update-summary.ts b/.agent/src/cli/prepare-rubrics-update-summary.ts new file mode 100644 index 0000000..e712d05 --- /dev/null +++ b/.agent/src/cli/prepare-rubrics-update-summary.ts @@ -0,0 +1,44 @@ +// CLI: build the rubrics-update summary comment body. +// Usage: node .agent/dist/cli/prepare-rubrics-update-summary.js +// Env: RESPONSE_FILE, RUBRICS_COMMITTED, RUBRICS_STEP_OUTCOME, RUBRICS_REF, +// PR_NUMBER, GITHUB_REPOSITORY, RUNNER_TEMP +// Outputs: body_file + +import { readFileSync, writeFileSync } from "node:fs"; +import { randomBytes } from "node:crypto"; +import { join } from "node:path"; +import { formatRubricsUpdateComment } from "../response.js"; +import { setOutput } from "../output.js"; + +const responseFile = process.env.RESPONSE_FILE || ""; +const rubricsCommitted = process.env.RUBRICS_COMMITTED === "true"; +const runSucceeded = process.env.RUBRICS_STEP_OUTCOME === "success"; +const rubricsRef = process.env.RUBRICS_REF || "agent/rubrics"; +const prNumber = process.env.PR_NUMBER || ""; +const repoSlug = process.env.GITHUB_REPOSITORY || ""; + +let summary = ""; +if (responseFile) { + try { + summary = readFileSync(responseFile, "utf8"); + } catch { + console.error(`Could not read response file: ${responseFile}`); + } +} + +const body = formatRubricsUpdateComment({ + prNumber, + rubricsRef, + rubricsCommitted, + runSucceeded, + repoSlug, + summary, +}); + +const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; +const bodyFile = join( + runnerTemp, + `rubrics-update-summary-${randomBytes(8).toString("hex")}.md`, +); +writeFileSync(bodyFile, body + "\n", "utf8"); +setOutput("body_file", bodyFile); diff --git a/.agent/src/cli/prepare-self-approve.ts b/.agent/src/cli/prepare-self-approve.ts new file mode 100644 index 0000000..750157e --- /dev/null +++ b/.agent/src/cli/prepare-self-approve.ts @@ -0,0 +1,117 @@ +// CLI: preflight self-approval before running the approval agent. +// Env: GITHUB_REPOSITORY, TARGET_NUMBER, TARGET_KIND, AGENT_ALLOW_SELF_APPROVE, +// SOURCE_RECOMMENDED_NEXT_STEP +// Outputs: should_run, head_sha, reason, body_file + +import { mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { + fetchAuthenticatedActorLogin, + fetchIssueCommentRecords, + fetchPrAuthorLogin, + fetchPrMeta, +} from "../github.js"; +import { setOutput } from "../output.js"; +import { + envFlagEnabled, + evaluateSelfApprovalActor, + evaluateSelfApprovalProvenance, + formatSelfApprovalBody, +} from "../self-approval.js"; + +function normalizeToken(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +function writeBodyFile(body: string): string { + const dir = mkdtempSync(join(tmpdir(), "sepo-self-approve-")); + const file = join(dir, "body.md"); + writeFileSync(file, body, "utf8"); + return file; +} + +function stop(reason: string): void { + const bodyFile = writeBodyFile(formatSelfApprovalBody({ + conclusion: "blocked", + reason, + approved: false, + })); + setOutput("should_run", "false"); + setOutput("head_sha", ""); + setOutput("reason", reason); + setOutput("body_file", bodyFile); +} + +const repo = process.env.GITHUB_REPOSITORY || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || process.env.PR_NUMBER || ""); +const targetKind = normalizeToken(process.env.TARGET_KIND || "pull_request"); +const allowSelfApprove = envFlagEnabled(process.env.AGENT_ALLOW_SELF_APPROVE); +const sourceRecommendedNextStep = normalizeToken(process.env.SOURCE_RECOMMENDED_NEXT_STEP || ""); +const isHumanDecisionGate = sourceRecommendedNextStep === "human_decision"; + +if (!allowSelfApprove) { + stop("AGENT_ALLOW_SELF_APPROVE is not enabled"); +} else if (targetKind !== "pull_request") { + stop("self-approval is only supported for pull requests"); +} else if (!repo || !targetNumber) { + stop("missing pull request target"); +} else { + let shouldContinue = true; + let headSha = ""; + let authenticatedActorLogin = ""; + + try { + const meta = fetchPrMeta(targetNumber, repo); + if (String(meta.state || "").trim().toUpperCase() !== "OPEN") { + stop(`pull request is ${String(meta.state || "not open").toLowerCase()}`); + shouldContinue = false; + } else if (!meta.headOid) { + stop("could not resolve pull request head SHA"); + shouldContinue = false; + } else { + headSha = meta.headOid; + } + } catch { + stop("could not read pull request metadata during self-approval preflight"); + shouldContinue = false; + } + + if (shouldContinue) { + try { + authenticatedActorLogin = fetchAuthenticatedActorLogin(); + const approvalActor = evaluateSelfApprovalActor({ + approvalActorLogin: authenticatedActorLogin, + prAuthorLogin: fetchPrAuthorLogin(targetNumber, repo), + }); + if (!approvalActor.allowed) { + stop(approvalActor.reason); + shouldContinue = false; + } + } catch { + stop("could not verify approval actor during self-approval preflight"); + shouldContinue = false; + } + } + + if (shouldContinue) { + try { + const provenance = evaluateSelfApprovalProvenance({ + comments: fetchIssueCommentRecords(targetNumber, repo), + trustedActorLogin: authenticatedActorLogin, + expectedHeadSha: headSha, + allowHumanDecisionGate: isHumanDecisionGate, + }); + if (!provenance.trusted) { + stop(provenance.reason); + } else { + setOutput("should_run", "true"); + setOutput("head_sha", headSha); + setOutput("reason", ""); + setOutput("body_file", ""); + } + } catch { + stop("could not read trusted review synthesis during self-approval preflight"); + } + } +} diff --git a/.agent/src/cli/push-pr-head.ts b/.agent/src/cli/push-pr-head.ts new file mode 100644 index 0000000..6b977a7 --- /dev/null +++ b/.agent/src/cli/push-pr-head.ts @@ -0,0 +1,22 @@ +// CLI: push the current HEAD back to a same-repository PR branch. +// Usage: node .agent/dist/cli/push-pr-head.js +// Env: BRANCH, GH_TOKEN, GITHUB_REPOSITORY, EXPECTED_HEAD_SHA, GITHUB_WORKSPACE +// Outputs: pushed, branch + +import { pushHeadUpdate } from "../git.js"; +import { setOutput } from "../output.js"; + +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const branch = process.env.BRANCH || ""; +const token = process.env.GH_TOKEN || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; +const expectedHead = process.env.EXPECTED_HEAD_SHA || ""; + +if (!branch || !token || !repo || !expectedHead) { + console.error("Missing BRANCH, GH_TOKEN, GITHUB_REPOSITORY, or EXPECTED_HEAD_SHA"); + process.exitCode = 2; +} else { + pushHeadUpdate({ branch, token, repo, cwd, expectedHead }); + setOutput("pushed", "true"); + setOutput("branch", branch); +} diff --git a/.agent/src/cli/resolve-approval.ts b/.agent/src/cli/resolve-approval.ts new file mode 100644 index 0000000..9e7b9e8 --- /dev/null +++ b/.agent/src/cli/resolve-approval.ts @@ -0,0 +1,168 @@ +// CLI: scan comments for pending approval requests. +// Usage: node .agent/dist/cli/resolve-approval.js +// Env: GITHUB_EVENT_PATH, GITHUB_EVENT_NAME, GITHUB_REPOSITORY, +// INPUT_MENTION, ACCESS_POLICY, REPOSITORY_PRIVATE +// Outputs: should_dispatch, is_discussion, request_comment_id, +// request_comment_body, route, target_kind, target_number, +// target_url, workflow, issue_title, issue_body, request_text, +// should_create_issue + +import { readFileSync } from "node:fs"; +import { execFileSync } from "node:child_process"; +import { setOutput } from "../output.js"; +import { DEFAULT_MENTION } from "../context.js"; +import { + type AccessPolicy, + getAllowedAssociationsForRoute, + isAssociationAllowedForRoute, + isKnownAuthorAssociation, + parseAccessPolicy, +} from "../access-policy.js"; +import { + isApprovalCommand, + isAgentApprovalComment, + findPendingRequestById, + parseApprovalCommand, + shouldCreateIssueFromApprovalRequest, +} from "../approval.js"; +import { fetchDiscussionComments } from "../discussion.js"; + +const GH_API_MAX_BUFFER = 10 * 1024 * 1024; + +interface Comment { + id: string | number; + body: string; + created_at: string; +} + +const eventPath = process.env.GITHUB_EVENT_PATH; +const eventName = process.env.GITHUB_EVENT_NAME || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; +const mention = process.env.INPUT_MENTION || DEFAULT_MENTION; +const isPublicRepo = String(process.env.REPOSITORY_PRIVATE || "").trim().toLowerCase() === "false"; + +function loadAccessPolicy(): AccessPolicy | null { + try { + return parseAccessPolicy(process.env.ACCESS_POLICY || ""); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Invalid AGENT_ACCESS_POLICY: ${msg}`); + return null; + } +} + +function fetchIssueComments(issueNumber: number | string): Comment[] { + const raw = execFileSync( + "gh", + ["api", "--paginate", `repos/${repo}/issues/${issueNumber}/comments`], + { stdio: ["pipe", "pipe", "pipe"], maxBuffer: GH_API_MAX_BUFFER }, + ).toString("utf8"); + + const comments: Comment[] = []; + // --paginate concatenates JSON arrays, so parse each array + for (const chunk of raw.split(/(?<=\])\s*(?=\[)/)) { + if (!chunk.trim()) continue; + try { + const arr = JSON.parse(chunk) as Array<{ id: number; body: string; created_at: string }>; + for (const c of arr) { + comments.push({ + id: String(c.id), + body: c.body || "", + created_at: c.created_at || "", + }); + } + } catch { + /* skip malformed chunks */ + } + } + return comments; +} + +function main(): void { + if (!eventPath || !eventName || !repo) { + console.error("Missing GITHUB_EVENT_PATH, GITHUB_EVENT_NAME, or GITHUB_REPOSITORY"); + setOutput("should_dispatch", "false"); + process.exitCode = 2; + return; + } + + const accessPolicy = loadAccessPolicy(); + if (!accessPolicy) { + setOutput("should_dispatch", "false"); + process.exitCode = 2; + return; + } + + const payload = JSON.parse(readFileSync(eventPath, "utf8")); + const commentBody = payload.comment?.body || ""; + + // Skip agent-managed approval request/status comments before doing any heavier work. + if (isAgentApprovalComment(commentBody)) { + console.log("Skipping agent-managed approval comment"); + setOutput("should_dispatch", "false"); + return; + } + + const association = payload.comment?.author_association || "NONE"; + if (!isKnownAuthorAssociation(association)) { + console.log(`Skipping unsupported approval association: ${association}`); + setOutput("should_dispatch", "false"); + return; + } + + if (!isApprovalCommand(commentBody, mention)) { + console.log("No valid approval command found"); + setOutput("should_dispatch", "false"); + return; + } + + const approvalCommand = parseApprovalCommand(commentBody, mention); + if (!approvalCommand) { + console.log("Approval command is missing a request ID"); + setOutput("should_dispatch", "false"); + return; + } + + const isDiscussion = eventName === "discussion_comment"; + let comments: Comment[]; + if (isDiscussion) { + const [owner, repoName] = repo.split("/"); + comments = fetchDiscussionComments(owner, repoName, payload.discussion?.number); + } else { + comments = fetchIssueComments(payload.issue?.number); + } + + const pending = findPendingRequestById(comments, approvalCommand.requestId); + if (!pending) { + console.log(`No pending agent approval request found for ${approvalCommand.requestId}`); + setOutput("should_dispatch", "false"); + return; + } + + const route = String(pending.request.route || ""); + if (!isAssociationAllowedForRoute(accessPolicy, route, association, isPublicRepo)) { + const allowed = getAllowedAssociationsForRoute(accessPolicy, route, isPublicRepo); + console.log(`Skipping unauthorized approval for route ${route || "default"} from ${association}; requires ${allowed.join(", ")}`); + setOutput("should_dispatch", "false"); + return; + } + + setOutput("should_dispatch", "true"); + setOutput("is_discussion", String(isDiscussion)); + setOutput("request_comment_id", String(pending.comment.id)); + setOutput("request_comment_body", pending.comment.body); + setOutput("route", route); + setOutput("target_kind", String(pending.request.target_kind || "")); + setOutput("target_number", String(pending.request.target_number || "")); + setOutput("target_url", String(pending.request.target_url || "")); + setOutput("workflow", String(pending.request.workflow || "")); + setOutput("issue_title", String(pending.request.issue_title || "")); + setOutput("issue_body", String(pending.request.issue_body || "")); + setOutput("request_text", String(pending.request.request_text || "")); + setOutput( + "should_create_issue", + String(shouldCreateIssueFromApprovalRequest(pending.request)), + ); +} + +main(); diff --git a/.agent/src/cli/resolve-dispatch.ts b/.agent/src/cli/resolve-dispatch.ts new file mode 100644 index 0000000..f60157c --- /dev/null +++ b/.agent/src/cli/resolve-dispatch.ts @@ -0,0 +1,102 @@ +// CLI: apply dispatch policy to agent triage output. +// Usage: node .agent/dist/cli/resolve-dispatch.js +// Env: RESPONSE_FILE, TARGET_KIND, AUTHOR_ASSOCIATION, REQUESTED_ROUTE, REQUEST_TEXT, +// REQUESTED_SKILL, ACCESS_POLICY, REPOSITORY_PRIVATE +// Outputs: route, needs_approval, confidence, summary, issue_title, issue_body, +// skill, base_pr + +import { readFileSync } from "node:fs"; +import { type AccessPolicy, parseAccessPolicy } from "../access-policy.js"; +import { setOutput } from "../output.js"; +import { + normalizeDispatch, + applyDispatchPolicy, + buildRequestedRouteDecision, + normalizeImplementIssueMetadata, +} from "../triage.js"; + +const responseFile = process.env.RESPONSE_FILE || ""; +const targetKind = process.env.TARGET_KIND || ""; +const authorAssociation = process.env.AUTHOR_ASSOCIATION || ""; +const requestedRoute = String(process.env.REQUESTED_ROUTE || "").trim().toLowerCase(); +const requestedSkill = String(process.env.REQUESTED_SKILL || "").trim(); +const requestText = process.env.REQUEST_TEXT || ""; +const isPublicRepo = String(process.env.REPOSITORY_PRIVATE || "").trim().toLowerCase() === "false"; + +function loadAccessPolicy(): AccessPolicy | null { + try { + return parseAccessPolicy(process.env.ACCESS_POLICY || ""); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Invalid AGENT_ACCESS_POLICY: ${msg}`); + return null; + } +} + +function emitDecision(accessPolicy: AccessPolicy): void { + try { + const isExplicit = Boolean(requestedRoute); + const implementMetadata = isExplicit && requestedRoute === "implement" && raw.trim() + ? (() => { + try { + return normalizeImplementIssueMetadata(raw); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Implement issue metadata was invalid; using fallback metadata: ${msg}`); + return null; + } + })() + : null; + const decision = isExplicit + ? buildRequestedRouteDecision(requestedRoute, requestText, implementMetadata) + : normalizeDispatch(raw); + const result = applyDispatchPolicy( + decision, + targetKind, + authorAssociation, + accessPolicy, + isPublicRepo, + isExplicit, + ); + + setOutput("route", result.route); + setOutput("needs_approval", String(result.needsApproval)); + setOutput("confidence", result.confidence); + setOutput("summary", result.summary); + setOutput("issue_title", result.issueTitle); + setOutput("issue_body", result.issueBody); + setOutput("skill", result.route === "skill" ? requestedSkill : ""); + setOutput("base_pr", result.route === "implement" ? result.basePr || "" : ""); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Dispatch resolution failed: ${msg}`); + // Fall back to answer route on parse failure + setOutput("route", "answer"); + setOutput("needs_approval", "false"); + setOutput("confidence", "low"); + setOutput("summary", "Could not parse dispatch response; falling back to answer."); + setOutput("issue_title", ""); + setOutput("issue_body", ""); + setOutput("skill", ""); + setOutput("base_pr", ""); + } +} + +let raw = ""; +if (responseFile) { + try { + raw = readFileSync(responseFile, "utf8"); + } catch { + console.error(`Could not read response file: ${responseFile}`); + process.exitCode = 1; + } +} + +if (requestedRoute || raw) { + const accessPolicy = loadAccessPolicy(); + if (!accessPolicy) { + process.exitCode = 2; + } else { + emitDecision(accessPolicy); + } +} diff --git a/.agent/src/cli/resolve-implementation-base.ts b/.agent/src/cli/resolve-implementation-base.ts new file mode 100644 index 0000000..3e804fa --- /dev/null +++ b/.agent/src/cli/resolve-implementation-base.ts @@ -0,0 +1,22 @@ +// CLI: resolve the base branch for agent-implement.yml. +// Env: BASE_BRANCH, BASE_PR, DEFAULT_BRANCH, GITHUB_REPOSITORY +// Outputs/env: base_branch/BASE_BRANCH + +import { + exportImplementationBase, + resolveImplementationBase, +} from "../implementation-base.js"; + +try { + const result = resolveImplementationBase({ + baseBranch: process.env.BASE_BRANCH, + basePr: process.env.BASE_PR, + defaultBranch: process.env.DEFAULT_BRANCH || "", + repo: process.env.GITHUB_REPOSITORY || "", + }); + exportImplementationBase(result); + console.log(`Resolved implementation base branch ${result.baseBranch} from ${result.source}`); +} catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + process.exitCode = 2; +} diff --git a/.agent/src/cli/resolve-scheduled-activity-gate.ts b/.agent/src/cli/resolve-scheduled-activity-gate.ts new file mode 100644 index 0000000..0b7d0fa --- /dev/null +++ b/.agent/src/cli/resolve-scheduled-activity-gate.ts @@ -0,0 +1,37 @@ +#!/usr/bin/env node +// CLI: resolve whether a scheduled workflow should skip expensive work. + +import { resolveScheduledActivityGate, type PushOptions } from "../scheduled-activity.js"; +import { setOutput } from "../output.js"; + +function buildOptions(): PushOptions { + const repo = process.env.GITHUB_REPOSITORY || process.env.REPO_SLUG || ""; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + return { repo, token: token || undefined }; +} + +try { + const result = resolveScheduledActivityGate({ + eventName: process.env.GITHUB_EVENT_NAME || "", + schedulePolicy: process.env.AGENT_SCHEDULE_POLICY || "", + workflow: process.env.WORKFLOW_FILENAME || "", + activityCount: process.env.ACTIVITY_COUNT || "", + dependencyRef: process.env.DEPENDENCY_REF || "", + dependencyField: process.env.DEPENDENCY_FIELD || "", + selfRef: process.env.SELF_REF || "", + selfField: process.env.SELF_FIELD || "", + cwd: process.env.GITHUB_WORKSPACE || process.cwd(), + pushOptions: buildOptions(), + }); + + setOutput("skip", result.skip ? "true" : "false"); + setOutput("mode", result.mode); + setOutput("reason", result.reason); + setOutput("dependency_value", result.dependencyValue); + setOutput("self_value", result.selfValue); + process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); +} catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + console.error(`Invalid scheduled activity gate configuration: ${message}`); + process.exitCode = 2; +} diff --git a/.agent/src/cli/resolve-self-approve.ts b/.agent/src/cli/resolve-self-approve.ts new file mode 100644 index 0000000..9d24231 --- /dev/null +++ b/.agent/src/cli/resolve-self-approve.ts @@ -0,0 +1,177 @@ +// CLI: resolve a self-approval agent response and optionally approve a PR. +// Env: RESPONSE_FILE, GITHUB_REPOSITORY, TARGET_NUMBER, TARGET_KIND, +// EXPECTED_HEAD_SHA, AGENT_ALLOW_SELF_APPROVE +// Outputs: conclusion, approved, handoff_context, reason, body_file + +import { mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { + fetchAuthenticatedActorLogin, + fetchIssueCommentRecords, + fetchPrAuthorLogin, + fetchPrMeta, + gh, +} from "../github.js"; +import { setOutput } from "../output.js"; +import { + envFlagEnabled, + evaluateSelfApprovalActor, + evaluateSelfApprovalProvenance, + formatSelfApprovalBody, + parseSelfApprovalDecision, + resolveSelfApproval, +} from "../self-approval.js"; + +function writeBodyFile(body: string): string { + const dir = mkdtempSync(join(tmpdir(), "sepo-self-approve-")); + const file = join(dir, "body.md"); + writeFileSync(file, body, "utf8"); + return file; +} + +function readResponse(): string { + const responseFile = process.env.RESPONSE_FILE || ""; + if (!responseFile) return ""; + try { + return readFileSync(responseFile, "utf8"); + } catch { + return ""; + } +} + +function currentRunUrl(): string { + const server = process.env.GITHUB_SERVER_URL || ""; + const repo = process.env.GITHUB_REPOSITORY || ""; + const runId = process.env.GITHUB_RUN_ID || ""; + return server && repo && runId ? `${server}/${repo}/actions/runs/${runId}` : ""; +} + +function submitApproval(repo: string, prNumber: number, headSha: string, body: string): void { + gh([ + "api", + "--method", + "POST", + `repos/${repo}/pulls/${prNumber}/reviews`, + "-f", + `commit_id=${headSha}`, + "-f", + "event=APPROVE", + "-f", + `body=${body}`, + ]); +} + +function normalizeTargetKind(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +const repo = process.env.GITHUB_REPOSITORY || ""; +const prNumber = Number(process.env.TARGET_NUMBER || process.env.PR_NUMBER || ""); +const targetKind = process.env.TARGET_KIND || "pull_request"; +const expectedHeadSha = process.env.EXPECTED_HEAD_SHA || ""; +const allowSelfApprove = envFlagEnabled(process.env.AGENT_ALLOW_SELF_APPROVE); +const decision = parseSelfApprovalDecision(readResponse()); + +let prState = ""; +let currentHeadSha = ""; +let metadataReadReason = ""; +let approvalActorAllowed = false; +let approvalActorReason = "approval actor could not be verified as distinct from pull request author"; +let approvalProvenanceTrusted = false; +let approvalProvenanceReason = "missing trusted review synthesis for self-approval"; +if (allowSelfApprove && normalizeTargetKind(targetKind) === "pull_request" && repo && prNumber) { + let authenticatedActorLogin = ""; + try { + const meta = fetchPrMeta(prNumber, repo); + prState = meta.state; + currentHeadSha = meta.headOid; + } catch { + metadataReadReason = "could not read pull request metadata during self-approval resolution"; + } + + try { + authenticatedActorLogin = fetchAuthenticatedActorLogin(); + const approvalActor = evaluateSelfApprovalActor({ + approvalActorLogin: authenticatedActorLogin, + prAuthorLogin: fetchPrAuthorLogin(prNumber, repo), + }); + approvalActorAllowed = approvalActor.allowed; + approvalActorReason = approvalActor.reason; + } catch { + approvalActorAllowed = false; + approvalActorReason = "could not verify approval actor differs from pull request author"; + } + + try { + const trustedActorLogin = authenticatedActorLogin || fetchAuthenticatedActorLogin(); + const provenance = evaluateSelfApprovalProvenance({ + comments: fetchIssueCommentRecords(prNumber, repo), + trustedActorLogin, + expectedHeadSha, + }); + approvalProvenanceTrusted = provenance.trusted; + approvalProvenanceReason = provenance.reason; + } catch { + approvalProvenanceTrusted = false; + approvalProvenanceReason = "could not read trusted review synthesis"; + } +} else if (allowSelfApprove && normalizeTargetKind(targetKind) === "pull_request") { + metadataReadReason = "missing pull request target"; +} + +let result = metadataReadReason + ? { + conclusion: "failed" as const, + shouldApprove: false, + reason: metadataReadReason, + handoffContext: decision?.handoffContext || "", + } + : resolveSelfApproval({ + allowSelfApprove, + targetKind, + prState, + expectedHeadSha, + currentHeadSha, + decision, + approvalActorAllowed, + approvalActorReason, + approvalProvenanceTrusted, + approvalProvenanceReason, + }); + +let approved = false; +if (result.shouldApprove) { + try { + submitApproval(repo, prNumber, expectedHeadSha, formatSelfApprovalBody({ + conclusion: result.conclusion, + reason: result.reason, + handoffContext: result.handoffContext, + approved: true, + runUrl: currentRunUrl(), + })); + approved = true; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + result = { + conclusion: "failed", + shouldApprove: false, + reason: `approval submission failed: ${message || "unknown error"}`, + handoffContext: result.handoffContext, + }; + } +} + +const body = formatSelfApprovalBody({ + conclusion: result.conclusion, + reason: result.reason, + handoffContext: result.handoffContext, + approved, + runUrl: currentRunUrl(), +}); +const bodyFile = writeBodyFile(body); +setOutput("conclusion", result.conclusion); +setOutput("approved", String(approved)); +setOutput("handoff_context", result.handoffContext); +setOutput("reason", result.reason); +setOutput("body_file", bodyFile); diff --git a/.agent/src/cli/resolve-self-merge.ts b/.agent/src/cli/resolve-self-merge.ts new file mode 100644 index 0000000..05bb870 --- /dev/null +++ b/.agent/src/cli/resolve-self-merge.ts @@ -0,0 +1,184 @@ +// CLI: preflight and perform deterministic self-merge for an approved PR. +// Env: GITHUB_REPOSITORY, TARGET_NUMBER, TARGET_KIND, AGENT_ALLOW_SELF_MERGE +// Outputs: conclusion, merged, auto_merge_enabled, status_post, reason, body_file + +import { mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { + enablePullRequestAutoMerge, + fetchAuthenticatedActorLogin, + fetchPrMergeMeta, + fetchPrReviewRecords, + markPullRequestReady, + mergePullRequest, +} from "../github.js"; +import { setOutput } from "../output.js"; +import { envFlagEnabled } from "../self-approval.js"; +import { + evaluateSelfMergeApproval, + formatSelfMergeBody, + resolveSelfMerge, + type SelfMergeApprovalResult, + type SelfMergeResolveResult, +} from "../self-merge.js"; + +function writeBodyFile(body: string): string { + const dir = mkdtempSync(join(tmpdir(), "sepo-self-merge-")); + const file = join(dir, "body.md"); + writeFileSync(file, body, "utf8"); + return file; +} + +function currentRunUrl(): string { + const server = process.env.GITHUB_SERVER_URL || ""; + const repo = process.env.GITHUB_REPOSITORY || ""; + const runId = process.env.GITHUB_RUN_ID || ""; + return server && repo && runId ? `${server}/${repo}/actions/runs/${runId}` : ""; +} + +function errorText(err: unknown): string { + const record = err as { message?: unknown; stderr?: unknown; stdout?: unknown }; + return [record.message, record.stderr, record.stdout] + .map((part) => { + if (Buffer.isBuffer(part)) return part.toString("utf8"); + return typeof part === "string" ? part : ""; + }) + .filter(Boolean) + .join("\n") || String(err); +} + +function normalizeTargetKind(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +const repo = process.env.GITHUB_REPOSITORY || ""; +const prNumber = Number(process.env.TARGET_NUMBER || process.env.PR_NUMBER || ""); +const targetKind = process.env.TARGET_KIND || "pull_request"; +const allowSelfMerge = envFlagEnabled(process.env.AGENT_ALLOW_SELF_MERGE); + +function resolveCurrentSelfMerge(): { + result: SelfMergeResolveResult; + verifiedHeadSha: string; +} { + if (!allowSelfMerge || normalizeTargetKind(targetKind) !== "pull_request" || !repo || !prNumber) { + return { + verifiedHeadSha: "", + result: resolveSelfMerge({ + allowSelfMerge, + targetKind, + prState: "", + isDraft: false, + currentHeadSha: "", + reviewDecision: "", + mergeStateStatus: "", + mergeable: "", + statusChecks: [], + approval: { + approved: false, + approvedHeadSha: "", + reason: repo && prNumber ? "missing current-head self-approval" : "missing pull request target", + }, + }), + }; + } + + try { + const meta = fetchPrMergeMeta(prNumber, repo); + let approval: SelfMergeApprovalResult; + try { + approval = evaluateSelfMergeApproval({ + reviews: fetchPrReviewRecords(prNumber, repo), + trustedActorLogin: fetchAuthenticatedActorLogin(), + currentHeadSha: meta.headOid, + }); + } catch { + approval = { + approved: false, + approvedHeadSha: "", + reason: "could not read current-head self-approval reviews", + }; + } + + const result = resolveSelfMerge({ + allowSelfMerge, + targetKind, + prState: meta.state, + isDraft: meta.isDraft, + currentHeadSha: meta.headOid, + reviewDecision: meta.reviewDecision, + mergeStateStatus: meta.mergeStateStatus, + mergeable: meta.mergeable, + autoMergeRequestExists: meta.autoMergeRequestExists, + statusChecks: meta.statusChecks, + approval, + }); + return { + verifiedHeadSha: approval.approved ? approval.approvedHeadSha || meta.headOid : "", + result, + }; + } catch { + return { + verifiedHeadSha: "", + result: { + conclusion: "failed", + nextStep: "none", + markReady: false, + reason: "could not read pull request metadata during self-merge preflight", + }, + }; + } +} + +let { result, verifiedHeadSha } = resolveCurrentSelfMerge(); +if (result.markReady) { + try { + markPullRequestReady(prNumber, repo); + ({ result, verifiedHeadSha } = resolveCurrentSelfMerge()); + } catch (err: unknown) { + result = { + conclusion: "failed", + nextStep: "none", + markReady: false, + reason: `mark ready failed: ${errorText(err) || "unknown error"}`, + }; + } +} + +if (result.nextStep === "merge") { + try { + mergePullRequest(prNumber, repo, verifiedHeadSha); + result = { ...result, conclusion: "merged" }; + } catch (err: unknown) { + result = { + conclusion: "failed", + nextStep: "none", + markReady: false, + reason: `merge failed: ${errorText(err) || "unknown error"}`, + }; + } +} else if (result.nextStep === "enable_auto_merge") { + try { + enablePullRequestAutoMerge(prNumber, repo, verifiedHeadSha); + result = { ...result, conclusion: "auto_merge_enabled" }; + } catch (err: unknown) { + result = { + conclusion: "failed", + nextStep: "none", + markReady: false, + reason: `auto-merge enable failed: ${errorText(err) || "unknown error"}`, + }; + } +} + +const bodyFile = writeBodyFile(formatSelfMergeBody({ + conclusion: result.conclusion, + reason: result.reason, + runUrl: currentRunUrl(), +})); +setOutput("conclusion", result.conclusion); +setOutput("merged", String(result.conclusion === "merged")); +setOutput("auto_merge_enabled", String(result.conclusion === "auto_merge_enabled")); +setOutput("status_post", "true"); +setOutput("reason", result.reason); +setOutput("body_file", bodyFile); diff --git a/.agent/src/cli/resolve-task-timeout.ts b/.agent/src/cli/resolve-task-timeout.ts new file mode 100644 index 0000000..d90731c --- /dev/null +++ b/.agent/src/cli/resolve-task-timeout.ts @@ -0,0 +1,38 @@ +#!/usr/bin/env node +// CLI: resolve the GitHub Actions step timeout for a run-agent-task invocation. +// +// Env: +// ROUTE current route (e.g., answer, review) +// AGENT_TASK_TIMEOUT_POLICY raw JSON policy string (optional) +// +// Outputs: +// minutes resolved positive integer timeout + +import { setOutput } from "../output.js"; +import { + getTaskTimeoutMinutesForRoute, + parseTaskTimeoutPolicy, +} from "../task-timeout-policy.js"; + +export function resolveTaskTimeoutMinutes(env: NodeJS.ProcessEnv = process.env): number { + const route = String(env.ROUTE || "").trim().toLowerCase(); + const policy = parseTaskTimeoutPolicy(env.AGENT_TASK_TIMEOUT_POLICY || ""); + return getTaskTimeoutMinutesForRoute(policy, route); +} + +export function runResolveTaskTimeoutCli(env: NodeJS.ProcessEnv = process.env): number { + try { + const minutes = resolveTaskTimeoutMinutes(env); + setOutput("minutes", String(minutes)); + console.log(`task timeout: ${minutes} minutes`); + return 0; + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Invalid AGENT_TASK_TIMEOUT_POLICY: ${msg}`); + return 2; + } +} + +if (require.main === module) { + process.exitCode = runResolveTaskTimeoutCli(); +} diff --git a/.agent/src/cli/rubrics/init.ts b/.agent/src/cli/rubrics/init.ts new file mode 100644 index 0000000..2e4f5a9 --- /dev/null +++ b/.agent/src/cli/rubrics/init.ts @@ -0,0 +1,41 @@ +#!/usr/bin/env node +// CLI: seed the default rubric branch layout. +// Usage: node .agent/dist/cli/rubrics/init.js --dir --repo + +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; +import { ensureRubricsStructure } from "../../rubrics.js"; + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + repo: { type: "string" }, + }, + allowPositionals: false, + strict: true, +} as const satisfies ParseArgsConfig; + +export function runRubricsInitCli(argv: string[], env: NodeJS.ProcessEnv = process.env): number { + let values: { dir?: string; repo?: string }; + try { + values = parseArgs({ ...ARG_CONFIG, args: argv }).values as typeof values; + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } + + const dir = resolve(values.dir || env.RUBRICS_DIR || process.cwd()); + const repo = values.repo || env.REPO_SLUG || env.GITHUB_REPOSITORY || ""; + if (!repo) { + console.error("Missing repository slug. Pass --repo or set REPO_SLUG/GITHUB_REPOSITORY."); + return 1; + } + + const result = ensureRubricsStructure(dir, repo); + console.log(JSON.stringify({ dir, repo, createdFiles: result.createdFiles }, null, 2)); + return 0; +} + +if (require.main === module) { + process.exitCode = runRubricsInitCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/rubrics/resolve-policy.ts b/.agent/src/cli/rubrics/resolve-policy.ts new file mode 100644 index 0000000..e033963 --- /dev/null +++ b/.agent/src/cli/rubrics/resolve-policy.ts @@ -0,0 +1,57 @@ +#!/usr/bin/env node +// CLI: resolve effective rubric access mode for a route. +// Env: AGENT_RUBRICS_POLICY, RUBRICS_MODE_OVERRIDE, ROUTE +// Outputs: mode, read_enabled, write_enabled + +import { setOutput } from "../../output.js"; +import { + getRubricsModeForRoute, + isRubricsMode, + isRubricsHardDisabledRoute, + parseRubricsPolicy, + rubricsModeAllowsRead, + rubricsModeAllowsWrite, + type RubricsMode, +} from "../../rubrics-policy.js"; + +export function resolveRubricsMode(env: NodeJS.ProcessEnv = process.env): RubricsMode { + const route = String(env.ROUTE || "").trim().toLowerCase(); + if (isRubricsHardDisabledRoute(route)) { + return "disabled"; + } + + const override = String(env.RUBRICS_MODE_OVERRIDE || "").trim().toLowerCase(); + if (override) { + if (!isRubricsMode(override)) { + throw new Error(`RUBRICS_MODE_OVERRIDE must be one of enabled, read-only, disabled (got ${override})`); + } + return override; + } + + const policy = parseRubricsPolicy(env.AGENT_RUBRICS_POLICY || ""); + return getRubricsModeForRoute(policy, route); +} + +export function runRubricsResolvePolicyCli(env: NodeJS.ProcessEnv = process.env): number { + try { + const mode = resolveRubricsMode(env); + setOutput("mode", mode); + setOutput("read_enabled", String(rubricsModeAllowsRead(mode))); + setOutput("write_enabled", String(rubricsModeAllowsWrite(mode))); + console.log(`rubrics mode: ${mode}`); + return 0; + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + console.error(`Invalid AGENT_RUBRICS_POLICY: ${msg}`); + // Fail closed: malformed policy disables rubric access for this run, but the + // workflow can continue without rubric steering. + setOutput("mode", "disabled"); + setOutput("read_enabled", "false"); + setOutput("write_enabled", "false"); + return 0; + } +} + +if (require.main === module) { + process.exitCode = runRubricsResolvePolicyCli(); +} diff --git a/.agent/src/cli/rubrics/select.ts b/.agent/src/cli/rubrics/select.ts new file mode 100644 index 0000000..2038de6 --- /dev/null +++ b/.agent/src/cli/rubrics/select.ts @@ -0,0 +1,120 @@ +#!/usr/bin/env node +// CLI: select route-applicable rubrics and render them as markdown. +// Usage: node .agent/dist/cli/rubrics/select.js --dir --route implement --query "..." + +import { writeFileSync } from "node:fs"; +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; +import { + formatRubricsForPrompt, + RUBRIC_DOMAINS, + type RubricDomain, + selectRubrics, +} from "../../rubrics.js"; +import { setOutput } from "../../output.js"; + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + route: { type: "string" }, + query: { type: "string" }, + limit: { type: "string" }, + domains: { type: "string" }, + "include-draft": { type: "boolean" }, + "all-routes": { type: "boolean" }, + "best-effort": { type: "boolean" }, + "output-file": { type: "string" }, + }, + allowPositionals: true, + strict: true, +} as const satisfies ParseArgsConfig; + +function parseLimit(value: string | undefined): number | undefined { + const normalized = String(value || "").trim().toLowerCase(); + if (normalized === "all") return Number.POSITIVE_INFINITY; + const n = Number(value || ""); + return Number.isInteger(n) && n > 0 ? n : undefined; +} + +function parseDomains(value: string | undefined): RubricDomain[] { + const valid = new Set(RUBRIC_DOMAINS); + const seen = new Set(); + const domains: RubricDomain[] = []; + for (const entry of String(value || "").split(",")) { + const domain = entry.trim().toLowerCase(); + if (!domain) continue; + if (!valid.has(domain)) { + throw new Error(`--domains entries must be one of ${RUBRIC_DOMAINS.join(", ")}`); + } + if (!seen.has(domain as RubricDomain)) { + seen.add(domain as RubricDomain); + domains.push(domain as RubricDomain); + } + } + return domains; +} + +export function runRubricsSelectCli(argv: string[], env: NodeJS.ProcessEnv = process.env): number { + let parsed: ReturnType>; + try { + parsed = parseArgs({ ...ARG_CONFIG, args: argv }); + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } + + const values = parsed.values as { + dir?: string; + route?: string; + query?: string; + limit?: string; + domains?: string; + "include-draft"?: boolean; + "all-routes"?: boolean; + "best-effort"?: boolean; + "output-file"?: string; + }; + const dir = resolve(values.dir || env.RUBRICS_DIR || process.cwd()); + const route = values.route || env.ROUTE || ""; + const query = values.query || parsed.positionals.join(" ") || env.REQUEST_TEXT || ""; + const outputFile = values["output-file"] || env.RUBRICS_CONTEXT_FILE || ""; + let domains: RubricDomain[] = []; + try { + domains = parseDomains(values.domains || env.RUBRICS_SELECT_DOMAINS); + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } + + const { selected, errors } = selectRubrics({ + rootDir: dir, + route, + query, + limit: parseLimit(values.limit || env.RUBRICS_LIMIT), + includeDraft: Boolean(values["include-draft"]), + allRoutes: Boolean(values["all-routes"]), + domains, + }); + + setOutput("selected_count", String(selected.length)); + setOutput("rubric_error_count", String(errors.length)); + + if (errors.length > 0) { + for (const error of errors) { + console.error(`::warning file=${error.path},title=Invalid rubric::${error.message}`); + } + if (!values["best-effort"]) return 1; + } + + const rendered = formatRubricsForPrompt(selected); + if (outputFile) { + writeFileSync(outputFile, rendered, "utf8"); + setOutput("context_file", outputFile); + } + process.stdout.write(rendered); + return 0; +} + +if (require.main === module) { + process.exitCode = runRubricsSelectCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/rubrics/validate.ts b/.agent/src/cli/rubrics/validate.ts new file mode 100644 index 0000000..ee5b01e --- /dev/null +++ b/.agent/src/cli/rubrics/validate.ts @@ -0,0 +1,45 @@ +#!/usr/bin/env node +// CLI: validate rubric YAML files. +// Usage: node .agent/dist/cli/rubrics/validate.js --dir + +import { parseArgs, type ParseArgsConfig } from "node:util"; +import { resolve } from "node:path"; +import { loadRubrics } from "../../rubrics.js"; +import { setOutput } from "../../output.js"; + +const ARG_CONFIG = { + options: { + dir: { type: "string" }, + }, + allowPositionals: false, + strict: true, +} as const satisfies ParseArgsConfig; + +export function runRubricsValidateCli(argv: string[], env: NodeJS.ProcessEnv = process.env): number { + let values: { dir?: string }; + try { + values = parseArgs({ ...ARG_CONFIG, args: argv }).values as typeof values; + } catch (err: unknown) { + console.error(err instanceof Error ? err.message : String(err)); + return 1; + } + + const dir = resolve(values.dir || env.RUBRICS_DIR || process.cwd()); + const { rubrics, errors } = loadRubrics(dir); + setOutput("rubric_count", String(rubrics.length)); + setOutput("rubric_error_count", String(errors.length)); + + if (errors.length > 0) { + for (const error of errors) { + console.error(`${error.path}: ${error.message}`); + } + return 1; + } + + console.log(`validated ${rubrics.length} rubric${rubrics.length === 1 ? "" : "s"} in ${dir}`); + return 0; +} + +if (require.main === module) { + process.exitCode = runRubricsValidateCli(process.argv.slice(2)); +} diff --git a/.agent/src/cli/session-backup.ts b/.agent/src/cli/session-backup.ts new file mode 100644 index 0000000..01a6993 --- /dev/null +++ b/.agent/src/cli/session-backup.ts @@ -0,0 +1,77 @@ +import { buildThreadKey } from "../envelope.js"; +import { setOutput } from "../output.js"; +import { + buildSessionBundleArtifactName, + createSessionBundle, + hasValidThreadTargetNumber, + parseSessionBundleMode, + shouldBackupSessionBundles, +} from "../session-bundle.js"; +import { parseSessionPolicy } from "../session-policy.js"; + +const repoSlug = process.env.GITHUB_REPOSITORY || ""; +const route = process.env.ROUTE || ""; +const targetKind = process.env.TARGET_KIND || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || "0"); +const lane = process.env.LANE || "default"; +const agent = process.env.ACPX_AGENT || ""; +const acpxRecordId = process.env.ACPX_RECORD_ID || ""; +const acpxSessionId = process.env.ACPX_SESSION_ID || ""; +const runId = process.env.GITHUB_RUN_ID || "run"; +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const homeDir = process.env.HOME || ""; +const runnerTemp = process.env.RUNNER_TEMP || undefined; +const policy = parseSessionPolicy(process.env.SESSION_POLICY); +const bundleMode = parseSessionBundleMode(process.env.SESSION_BUNDLE_MODE); + +setOutput("bundle_created", "false"); +setOutput("bundle_file", ""); +setOutput("artifact_name", ""); +setOutput("file_count", "0"); +setOutput("total_size_bytes", "0"); + +if (!policy) { + console.error("Missing or invalid SESSION_POLICY"); + process.exitCode = 2; +} else if (!shouldBackupSessionBundles(bundleMode, policy)) { + process.exit(0); +} else if ( + !repoSlug || + !route || + !targetKind || + !hasValidThreadTargetNumber(targetKind, targetNumber) || + !agent +) { + console.error("Missing repo identity inputs for session backup"); + process.exitCode = 2; +} else if (!acpxRecordId || !acpxSessionId) { + console.log("No acpx session identity was emitted; skipping session bundle backup."); +} else { + const threadKey = buildThreadKey({ + repo_slug: repoSlug, + route, + target_kind: targetKind, + target_number: targetNumber, + lane, + }); + const bundle = createSessionBundle({ + agent, + threadKey, + repoSlug, + cwd, + acpxRecordId, + acpxSessionId, + homeDir, + runnerTemp, + }); + + if (!bundle) { + console.log("No session files discovered for backup."); + } else { + setOutput("bundle_created", "true"); + setOutput("bundle_file", bundle.bundlePath); + setOutput("artifact_name", buildSessionBundleArtifactName(threadKey, runId)); + setOutput("file_count", String(bundle.fileCount)); + setOutput("total_size_bytes", String(bundle.totalSizeBytes)); + } +} diff --git a/.agent/src/cli/session-register.ts b/.agent/src/cli/session-register.ts new file mode 100644 index 0000000..2638628 --- /dev/null +++ b/.agent/src/cli/session-register.ts @@ -0,0 +1,93 @@ +import { buildThreadKey } from "../envelope.js"; +import { configureBotIdentity } from "../git.js"; +import { setOutput } from "../output.js"; +import { + DEBUG_SESSION_BUNDLE_BACKEND, + RESTORABLE_SESSION_BUNDLE_BACKEND, + hasValidThreadTargetNumber, + parseSessionBundleMode, + shouldBackupSessionBundles, + shouldRestoreSessionBundles, +} from "../session-bundle.js"; +import { parseSessionPolicy } from "../session-policy.js"; +import { + type PushOptions, + getThreadState, + markThreadBundleStored, +} from "../thread-state.js"; + +function buildThreadStateOptions(): PushOptions { + const opts: PushOptions = { repo: process.env.GITHUB_REPOSITORY || "" }; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + if (token) opts.token = token; + return opts; +} + +const repoRoot = process.env.GITHUB_WORKSPACE || process.cwd(); +const repoSlug = process.env.GITHUB_REPOSITORY || ""; +const route = process.env.ROUTE || ""; +const targetKind = process.env.TARGET_KIND || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || "0"); +const lane = process.env.LANE || "default"; +const artifactId = process.env.SESSION_BUNDLE_ARTIFACT_ID || ""; +const artifactName = process.env.SESSION_BUNDLE_ARTIFACT_NAME || ""; +const runId = process.env.GITHUB_RUN_ID || ""; +const sessionRecordId = process.env.SESSION_RECORD_ID || ""; +const sessionId = process.env.SESSION_ID || ""; +const policy = parseSessionPolicy(process.env.SESSION_POLICY); +const bundleMode = parseSessionBundleMode(process.env.SESSION_BUNDLE_MODE); + +setOutput("registered", "false"); + +if (!policy) { + console.error("Missing or invalid SESSION_POLICY"); + process.exitCode = 2; +} else if (!shouldBackupSessionBundles(bundleMode, policy)) { + process.exit(0); +} else if ( + !artifactId || + !artifactName || + !repoSlug || + !route || + !targetKind || + !hasValidThreadTargetNumber(targetKind, targetNumber) +) { + console.log("No session bundle artifact metadata to register."); +} else { + const threadKey = buildThreadKey({ + repo_slug: repoSlug, + route, + target_kind: targetKind, + target_number: targetNumber, + lane, + }); + const threadStateOpts = buildThreadStateOptions(); + configureBotIdentity(repoRoot); + + const state = getThreadState(threadKey, repoRoot, threadStateOpts); + if (!state) { + console.log("No thread state found while registering session bundle; skipping."); + } else if ( + (sessionId && state.acpxSessionId !== sessionId) || + (sessionRecordId && state.acpxRecordId !== sessionRecordId) + ) { + console.log( + "Thread state session identity no longer matches the uploaded bundle; skipping registration.", + ); + } else { + markThreadBundleStored( + threadKey, + repoRoot, + { + session_bundle_backend: shouldRestoreSessionBundles(bundleMode, policy) + ? RESTORABLE_SESSION_BUNDLE_BACKEND + : DEBUG_SESSION_BUNDLE_BACKEND, + session_bundle_artifact_id: artifactId, + session_bundle_artifact_name: artifactName, + session_bundle_run_id: runId, + }, + threadStateOpts, + ); + setOutput("registered", "true"); + } +} diff --git a/.agent/src/cli/session-restore.ts b/.agent/src/cli/session-restore.ts new file mode 100644 index 0000000..bb37874 --- /dev/null +++ b/.agent/src/cli/session-restore.ts @@ -0,0 +1,316 @@ +import { mkdtempSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execFileSync } from "node:child_process"; + +import { buildThreadKey } from "../envelope.js"; +import { configureBotIdentity } from "../git.js"; +import { setOutput } from "../output.js"; +import { + findSessionBundleArchive, + hasValidThreadTargetNumber, + isRestorableSessionBundleBackend, + parseSessionBundleMode, + restoreSessionBundle, + shouldRestoreSessionBundles, +} from "../session-bundle.js"; +import { parseSessionPolicy } from "../session-policy.js"; +import { + type PushOptions, + type ThreadState, + getThreadState, + markThreadBundleRestore, +} from "../thread-state.js"; + +function buildThreadStateOptions(): PushOptions { + const opts: PushOptions = { repo: process.env.GITHUB_REPOSITORY || "" }; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + if (token) opts.token = token; + return opts; +} + +function setDefaultOutputs(): void { + setOutput("restore_status", "not_applicable"); + setOutput("restore_error", ""); + setOutput("artifact_name", ""); + setOutput("artifact_run_id", ""); + setOutput("fork_restore_status", "not_attempted"); + setOutput("fork_restore_error", ""); + setOutput("fork_from_thread_key", ""); + setOutput("fork_acpx_session_id", ""); + setOutput("fork_artifact_name", ""); + setOutput("fork_artifact_run_id", ""); +} + +function setForkOutputs(args: { + status: string; + error?: string; + threadKey?: string; + acpxSessionId?: string; + artifactName?: string; + artifactRunId?: string; +}): void { + setOutput("fork_restore_status", args.status); + setOutput("fork_restore_error", args.error || ""); + setOutput("fork_from_thread_key", args.threadKey || ""); + setOutput("fork_acpx_session_id", args.acpxSessionId || ""); + setOutput("fork_artifact_name", args.artifactName || ""); + setOutput("fork_artifact_run_id", args.artifactRunId || ""); +} + +function restoreArtifactBundle(args: { + repoSlug: string; + repoRoot: string; + runnerTemp: string; + homeDir: string; + artifactName: string; + artifactRunId: string; +}): void { + const downloadDir = mkdtempSync(join(args.runnerTemp, "session-bundle-download-")); + try { + execFileSync( + "gh", + [ + "run", + "download", + args.artifactRunId, + "--repo", + args.repoSlug, + "-n", + args.artifactName, + "-D", + downloadDir, + ], + { + cwd: args.repoRoot, + env: process.env, + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: 20 * 1024 * 1024, + }, + ); + + const bundlePath = findSessionBundleArchive(downloadDir); + if (!bundlePath) { + throw new Error(`Artifact ${args.artifactName} did not contain a .tgz bundle`); + } + + restoreSessionBundle(bundlePath, args.homeDir); + } finally { + rmSync(downloadDir, { recursive: true, force: true }); + } +} + +type DestinationRestoreStatus = "restored" | "not_available" | "failed"; + +function tryRestoreDestination(args: { + threadKey: string; + state: ThreadState | null; + repoSlug: string; + repoRoot: string; + runnerTemp: string; + homeDir: string; + threadStateOpts: PushOptions; +}): DestinationRestoreStatus { + const artifactName = args.state?.session_bundle_artifact_name || ""; + const artifactRunId = args.state?.session_bundle_run_id || ""; + const artifactBackend = args.state?.session_bundle_backend || ""; + + if (!artifactName || !artifactRunId || !isRestorableSessionBundleBackend(artifactBackend)) { + markThreadBundleRestore( + args.threadKey, + args.repoRoot, + { bundle_restore_status: "not_available", last_bundle_restore_error: "" }, + args.threadStateOpts, + ); + setOutput("restore_status", "not_available"); + return "not_available"; + } + + try { + restoreArtifactBundle({ + repoSlug: args.repoSlug, + repoRoot: args.repoRoot, + runnerTemp: args.runnerTemp, + homeDir: args.homeDir, + artifactName, + artifactRunId, + }); + markThreadBundleRestore( + args.threadKey, + args.repoRoot, + { bundle_restore_status: "restored", last_bundle_restore_error: "" }, + args.threadStateOpts, + ); + setOutput("restore_status", "restored"); + setOutput("artifact_name", artifactName); + setOutput("artifact_run_id", artifactRunId); + return "restored"; + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + markThreadBundleRestore( + args.threadKey, + args.repoRoot, + { bundle_restore_status: "failed", last_bundle_restore_error: msg }, + args.threadStateOpts, + ); + setOutput("restore_status", "failed"); + setOutput("restore_error", msg); + setOutput("artifact_name", artifactName); + setOutput("artifact_run_id", artifactRunId); + console.warn(`Session bundle restore failed: ${msg}`); + return "failed"; + } +} + +function tryRestoreForkSource(args: { + sourceThreadKey: string; + destinationThreadKey: string; + repoSlug: string; + repoRoot: string; + runnerTemp: string; + homeDir: string; + threadStateOpts: PushOptions; +}): void { + const sourceThreadKey = String(args.sourceThreadKey || "").trim(); + if (!sourceThreadKey || sourceThreadKey === args.destinationThreadKey) { + return; + } + + let state: ThreadState | null = null; + try { + state = getThreadState(sourceThreadKey, args.repoRoot, args.threadStateOpts); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + setForkOutputs({ status: "failed", error: msg, threadKey: sourceThreadKey }); + console.warn(`Session fork source lookup failed: ${msg}`); + return; + } + + if (!state) { + setForkOutputs({ status: "not_available", threadKey: sourceThreadKey }); + return; + } + + const acpxSessionId = state.acpxSessionId || ""; + if (!acpxSessionId) { + setForkOutputs({ status: "no_session_identity", threadKey: sourceThreadKey }); + return; + } + + const artifactName = state.session_bundle_artifact_name || ""; + const artifactRunId = state.session_bundle_run_id || ""; + const artifactBackend = state.session_bundle_backend || ""; + if (!artifactName || !artifactRunId || !isRestorableSessionBundleBackend(artifactBackend)) { + setForkOutputs({ + status: "not_available", + threadKey: sourceThreadKey, + acpxSessionId, + }); + return; + } + + try { + restoreArtifactBundle({ + repoSlug: args.repoSlug, + repoRoot: args.repoRoot, + runnerTemp: args.runnerTemp, + homeDir: args.homeDir, + artifactName, + artifactRunId, + }); + setOutput("restore_status", "restored_from_fork"); + setOutput("restore_error", ""); + setOutput("artifact_name", artifactName); + setOutput("artifact_run_id", artifactRunId); + setForkOutputs({ + status: "restored", + threadKey: sourceThreadKey, + acpxSessionId, + artifactName, + artifactRunId, + }); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + setOutput("restore_status", "failed"); + setOutput("restore_error", msg); + setForkOutputs({ + status: "failed", + error: msg, + threadKey: sourceThreadKey, + acpxSessionId, + artifactName, + artifactRunId, + }); + console.warn(`Session fork source restore failed: ${msg}`); + } +} + +const repoRoot = process.env.GITHUB_WORKSPACE || process.cwd(); +const repoSlug = process.env.GITHUB_REPOSITORY || ""; +const route = process.env.ROUTE || ""; +const targetKind = process.env.TARGET_KIND || ""; +const targetNumber = Number(process.env.TARGET_NUMBER || "0"); +const lane = process.env.LANE || "default"; +const homeDir = process.env.HOME || ""; +const runnerTemp = process.env.RUNNER_TEMP || tmpdir(); +const policy = parseSessionPolicy(process.env.SESSION_POLICY); +const bundleMode = parseSessionBundleMode(process.env.SESSION_BUNDLE_MODE); +const forkFromThreadKey = String(process.env.SESSION_FORK_FROM_THREAD_KEY || "").trim(); + +setDefaultOutputs(); + +if (!policy) { + console.error("Missing or invalid SESSION_POLICY"); + process.exitCode = 2; +} else if ( + !repoSlug || + !route || + !targetKind || + !hasValidThreadTargetNumber(targetKind, targetNumber) +) { + console.error("Missing repo or thread identity inputs for session restore"); + process.exitCode = 2; +} else if (!shouldRestoreSessionBundles(bundleMode, policy)) { + setOutput("restore_status", "not_applicable"); + setForkOutputs({ status: "not_applicable" }); +} else { + try { + const threadKey = buildThreadKey({ + repo_slug: repoSlug, + route, + target_kind: targetKind, + target_number: targetNumber, + lane, + }); + const threadStateOpts = buildThreadStateOptions(); + configureBotIdentity(repoRoot); + + const state = getThreadState(threadKey, repoRoot, threadStateOpts); + const destinationRestoreStatus = tryRestoreDestination({ + threadKey, + state, + repoSlug, + repoRoot, + runnerTemp, + homeDir, + threadStateOpts, + }); + + if (destinationRestoreStatus !== "restored" && !state?.acpxSessionId) { + tryRestoreForkSource({ + sourceThreadKey: forkFromThreadKey, + destinationThreadKey: threadKey, + repoSlug, + repoRoot, + runnerTemp, + homeDir, + threadStateOpts, + }); + } + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + setOutput("restore_status", "failed"); + setOutput("restore_error", msg); + console.warn(`Session bundle restore setup failed: ${msg}`); + } +} diff --git a/.agent/src/cli/update-approval-comment.ts b/.agent/src/cli/update-approval-comment.ts new file mode 100644 index 0000000..5a76fde --- /dev/null +++ b/.agent/src/cli/update-approval-comment.ts @@ -0,0 +1,45 @@ +// CLI: update an approval request comment to mark it as satisfied. +// Usage: node .agent/dist/cli/update-approval-comment.js +// Env: REQUEST_COMMENT_ID, REQUEST_COMMENT_BODY, IS_DISCUSSION, +// ROUTE, WORKFLOW, CREATED_ISSUE_URL, RUN_URL, APPROVER, +// GITHUB_REPOSITORY + +import { execFileSync } from "node:child_process"; +import { markApprovalRequestSatisfied } from "../approval.js"; +import { updateDiscussionComment } from "../discussion.js"; + +const commentId = process.env.REQUEST_COMMENT_ID || ""; +const commentBody = process.env.REQUEST_COMMENT_BODY || ""; +const isDiscussion = process.env.IS_DISCUSSION === "true"; +const route = process.env.ROUTE || ""; +const workflow = process.env.WORKFLOW || ""; +const createdIssueUrl = process.env.CREATED_ISSUE_URL || ""; +const runUrl = process.env.RUN_URL || ""; +const approver = process.env.APPROVER || ""; +const repo = process.env.GITHUB_REPOSITORY || ""; + +if (!commentId || !commentBody) { + console.error("Missing REQUEST_COMMENT_ID or REQUEST_COMMENT_BODY"); + process.exitCode = 1; +} else { + const newBody = markApprovalRequestSatisfied(commentBody, approver, { + route: route || undefined, + workflow: workflow || undefined, + issueUrl: createdIssueUrl || undefined, + runUrl: runUrl || undefined, + }); + + if (isDiscussion) { + updateDiscussionComment(commentId, newBody); + } else { + execFileSync( + "gh", + [ + "api", "--method", "PATCH", + `repos/${repo}/issues/comments/${commentId}`, + "-f", `body=${newBody}`, + ], + { stdio: "pipe", maxBuffer: 10 * 1024 * 1024 }, + ); + } +} diff --git a/.agent/src/cli/verify.ts b/.agent/src/cli/verify.ts new file mode 100644 index 0000000..304f958 --- /dev/null +++ b/.agent/src/cli/verify.ts @@ -0,0 +1,31 @@ +// CLI: run post-agent verification. +// Usage: node .agent/dist/cli/verify.js +// Env: GITHUB_WORKSPACE, HEAD_CHANGED, VERIFY_BASE_SHA +// Outputs: verify_exit_code, has_changes + +import { hasChanges } from "../git.js"; +import { runVerification, shouldRunVerification } from "../verify.js"; +import { setOutput } from "../output.js"; + +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const headChanged = process.env.HEAD_CHANGED === "true"; +const verifyBaseSha = process.env.VERIFY_BASE_SHA || ""; +const worktreeChanged = hasChanges(cwd); + +if (!shouldRunVerification(worktreeChanged, headChanged)) { + setOutput("verify_exit_code", "0"); + setOutput("has_changes", "false"); + process.exit(0); +} + +if (headChanged && !verifyBaseSha) { + console.error("HEAD_CHANGED=true requires VERIFY_BASE_SHA for history-aware verification."); + setOutput("verify_exit_code", "1"); + setOutput("has_changes", String(worktreeChanged)); + process.exit(1); +} + +const result = runVerification(cwd, { baseSha: verifyBaseSha }); +setOutput("verify_exit_code", String(result.exitCode)); +setOutput("has_changes", String(worktreeChanged)); +process.exitCode = result.exitCode; diff --git a/.agent/src/cli/write-scheduled-state.ts b/.agent/src/cli/write-scheduled-state.ts new file mode 100644 index 0000000..d026316 --- /dev/null +++ b/.agent/src/cli/write-scheduled-state.ts @@ -0,0 +1,48 @@ +#!/usr/bin/env node +// CLI: write a ref-backed scheduled workflow state record. + +import { configureBotIdentity } from "../git.js"; +import { fetchJsonState, writeJsonState, type PushOptions } from "../scheduled-activity.js"; +import { setOutput } from "../output.js"; + +function buildOptions(): PushOptions { + const repo = process.env.GITHUB_REPOSITORY || process.env.REPO_SLUG || ""; + const token = process.env.INPUT_GITHUB_TOKEN || process.env.GH_TOKEN || ""; + return { repo, token: token || undefined }; +} + +const ref = process.env.SCHEDULE_STATE_REF || ""; +const field = process.env.SCHEDULE_STATE_FIELD || ""; +const value = process.env.SCHEDULE_STATE_VALUE || new Date().toISOString(); +const repoSlug = process.env.REPO_SLUG || process.env.GITHUB_REPOSITORY || ""; +const runUrl = process.env.SCHEDULE_LAST_RUN_URL || ""; +const cwd = process.env.GITHUB_WORKSPACE || process.cwd(); +const options = buildOptions(); + +setOutput("written", "false"); + +if (!ref) { + console.error("Missing SCHEDULE_STATE_REF"); + process.exitCode = 2; +} else if (!field) { + console.error("Missing SCHEDULE_STATE_FIELD"); + process.exitCode = 2; +} else { + configureBotIdentity(cwd); + + const now = new Date().toISOString(); + const existing = fetchJsonState(ref, cwd, options) || {}; + const next = { + ...existing, + schema_version: 1, + repo_slug: repoSlug || existing.repo_slug || "", + [field]: value, + last_run_url: runUrl || existing.last_run_url || "", + created_at: typeof existing.created_at === "string" ? existing.created_at : now, + updated_at: now, + }; + + writeJsonState(ref, next, cwd, options); + setOutput("written", "true"); + process.stdout.write(`${JSON.stringify(next, null, 2)}\n`); +} diff --git a/.agent/src/context.ts b/.agent/src/context.ts new file mode 100644 index 0000000..90d0d37 --- /dev/null +++ b/.agent/src/context.ts @@ -0,0 +1,289 @@ +// Normalizes supported GitHub event payloads into the portal's common +// trigger shape so later steps can gate on associations, mentions, reactions, +// and response targets without branching on every event type again. + +import { hasLiveMention } from "./mentions.js"; + +export const DEFAULT_TRUSTED_ASSOCIATIONS = new Set([ + "OWNER", + "MEMBER", + "COLLABORATOR", + "CONTRIBUTOR", +]); + +export const DEFAULT_MENTION = "@sepo-agent"; + +export interface PortalEventContext { + body: string; + sourceKind: string; + targetKind: string; + targetNumber: string; + targetUrl: string; + reactionSubjectId: string; + responseKind: string; + sourceCommentId?: string; + sourceCommentUrl?: string; + reviewCommentId?: string; + discussionNodeId?: string; + discussionCommentNodeId?: string; +} + +// eslint-disable-next-line @typescript-eslint/no-explicit-any +type Payload = Record; + +function joinTitleAndBody(title: string, body: string): string { + return [title, body].filter(Boolean).join("\n\n"); +} + +function getPreviousEditedBody(eventName: string, payload: Payload): string | null { + if (payload.action !== "edited") { + return null; + } + + if (eventName === "issues") { + const title = payload.changes?.title?.from ?? payload.issue?.title ?? ""; + const body = payload.changes?.body?.from ?? payload.issue?.body ?? ""; + return joinTitleAndBody(title, body); + } + + if (eventName === "pull_request" || eventName === "pull_request_target") { + const title = payload.changes?.title?.from ?? payload.pull_request?.title ?? ""; + const body = payload.changes?.body?.from ?? payload.pull_request?.body ?? ""; + return joinTitleAndBody(title, body); + } + + if (eventName === "discussion") { + const title = payload.changes?.title?.from ?? payload.discussion?.title ?? ""; + const body = payload.changes?.body?.from ?? payload.discussion?.body ?? ""; + return joinTitleAndBody(title, body); + } + + if (eventName === "issue_comment") { + return payload.changes?.body?.from ?? payload.comment?.body ?? ""; + } + + if (eventName === "pull_request_review_comment") { + return payload.changes?.body?.from ?? payload.comment?.body ?? ""; + } + + if (eventName === "pull_request_review") { + return payload.changes?.body?.from ?? payload.review?.body ?? ""; + } + + if (eventName === "discussion_comment") { + return payload.changes?.body?.from ?? payload.comment?.body ?? ""; + } + + return null; +} + +/** + * Returns the author association field for the current trigger shape. + */ +export function getAuthorAssociation(eventName: string, payload: Payload): string { + if (eventName === "issue_comment") { + return payload.comment?.author_association || "NONE"; + } + if (eventName === "pull_request_review_comment") { + return payload.comment?.author_association || "NONE"; + } + if (eventName === "pull_request_review") { + return payload.review?.author_association || "NONE"; + } + if (eventName === "issues") { + return payload.issue?.author_association || "NONE"; + } + if (eventName === "pull_request" || eventName === "pull_request_target") { + return payload.pull_request?.author_association || "NONE"; + } + if (eventName === "discussion") { + return ( + payload.discussion?.authorAssociation || + payload.discussion?.author_association || + "NONE" + ); + } + if (eventName === "discussion_comment") { + return ( + payload.comment?.authorAssociation || + payload.comment?.author_association || + "NONE" + ); + } + return "NONE"; +} + +/** + * Extracts the requesting user's login from the event payload. + */ +export function getRequestedBy(eventName: string, payload: Payload): string { + if (eventName === "issue_comment" || eventName === "pull_request_review_comment") { + return payload.comment?.user?.login || ""; + } + if (eventName === "pull_request_review") { + return payload.review?.user?.login || ""; + } + if (eventName === "issues") { + return payload.issue?.user?.login || ""; + } + if (eventName === "pull_request" || eventName === "pull_request_target") { + return payload.pull_request?.user?.login || ""; + } + if (eventName === "discussion") { + return payload.discussion?.user?.login || ""; + } + if (eventName === "discussion_comment") { + return payload.comment?.user?.login || ""; + } + return ""; +} + +/** + * Extracts a normalized portal event context from a supported webhook payload. + */ +export function extractEventContext( + eventName: string, + payload: Payload, +): PortalEventContext { + if (eventName === "issues") { + const title = payload.issue?.title || ""; + const body = payload.issue?.body || ""; + return { + body: joinTitleAndBody(title, body), + sourceKind: "issue", + targetKind: "issue", + targetNumber: String(payload.issue?.number || ""), + targetUrl: payload.issue?.html_url || "", + reactionSubjectId: payload.issue?.node_id || "", + responseKind: "issue_comment", + }; + } + + if (eventName === "pull_request" || eventName === "pull_request_target") { + const title = payload.pull_request?.title || ""; + const body = payload.pull_request?.body || ""; + return { + body: joinTitleAndBody(title, body), + sourceKind: "pull_request", + targetKind: "pull_request", + targetNumber: String(payload.pull_request?.number || ""), + targetUrl: payload.pull_request?.html_url || "", + reactionSubjectId: payload.pull_request?.node_id || "", + responseKind: "issue_comment", + }; + } + + if (eventName === "issue_comment") { + return { + body: payload.comment?.body || "", + sourceKind: "issue_comment", + sourceCommentId: String(payload.comment?.id || ""), + sourceCommentUrl: payload.comment?.html_url || "", + targetKind: payload.issue?.pull_request ? "pull_request" : "issue", + targetNumber: String(payload.issue?.number || ""), + targetUrl: payload.issue?.html_url || "", + reactionSubjectId: payload.comment?.node_id || "", + responseKind: "issue_comment", + }; + } + + if (eventName === "pull_request_review_comment") { + return { + body: payload.comment?.body || "", + sourceKind: "pull_request_review_comment", + sourceCommentId: String(payload.comment?.id || ""), + sourceCommentUrl: payload.comment?.html_url || "", + targetKind: "pull_request", + targetNumber: String(payload.pull_request?.number || ""), + targetUrl: payload.pull_request?.html_url || "", + reactionSubjectId: payload.comment?.node_id || "", + responseKind: "review_comment_reply", + reviewCommentId: String(payload.comment?.id || ""), + }; + } + + if (eventName === "pull_request_review") { + return { + body: payload.review?.body || "", + sourceKind: "pull_request_review", + sourceCommentId: String(payload.review?.id || ""), + sourceCommentUrl: payload.review?.html_url || "", + targetKind: "pull_request", + targetNumber: String(payload.pull_request?.number || ""), + targetUrl: payload.pull_request?.html_url || "", + reactionSubjectId: payload.review?.node_id || "", + responseKind: "issue_comment", + }; + } + + if (eventName === "discussion") { + const title = payload.discussion?.title || ""; + const body = payload.discussion?.body || ""; + return { + body: joinTitleAndBody(title, body), + sourceKind: "discussion", + targetKind: "discussion", + targetNumber: String(payload.discussion?.number || ""), + targetUrl: + payload.discussion?.html_url || payload.discussion?.url || "", + reactionSubjectId: payload.discussion?.node_id || "", + responseKind: "discussion_comment", + discussionNodeId: payload.discussion?.node_id || "", + }; + } + + if (eventName === "discussion_comment") { + return { + body: payload.comment?.body || "", + sourceKind: "discussion_comment", + targetKind: "discussion", + targetNumber: String(payload.discussion?.number || ""), + targetUrl: + payload.discussion?.html_url || payload.discussion?.url || "", + reactionSubjectId: payload.comment?.node_id || "", + responseKind: "discussion_comment", + discussionNodeId: payload.discussion?.node_id || "", + discussionCommentNodeId: payload.comment?.node_id || "", + }; + } + + throw new Error(`Unsupported event for agent mention: ${eventName}`); +} + +/** + * Filters out bot-authored events before the portal spends effort on them. + */ +export function shouldSkipSender(payload: Payload): boolean { + const senderLogin = payload.sender?.login || ""; + const senderType = payload.sender?.type || ""; + return ( + senderType === "Bot" || + /\[bot\]$/i.test(senderLogin) || + senderLogin === "github-actions" + ); +} + +/** + * Checks whether this payload should trigger a mention-based response. + * Edited events only trigger when the live mention state changes false -> true. + */ +export function shouldRespondToMention( + eventName: string, + payload: Payload, + mention: string, +): boolean { + const currentBody = extractEventContext(eventName, payload).body; + if (!hasLiveMention(currentBody, mention)) { + return false; + } + + const previousBody = getPreviousEditedBody(eventName, payload); + if (previousBody === null) { + return true; + } + + return !hasLiveMention(previousBody, mention); +} + +// Re-export for convenient access from context module consumers +export { hasLiveMention }; diff --git a/.agent/src/discussion-transcript.ts b/.agent/src/discussion-transcript.ts new file mode 100644 index 0000000..60a8961 --- /dev/null +++ b/.agent/src/discussion-transcript.ts @@ -0,0 +1,321 @@ +import type { GraphQLClient } from "./github-graphql.js"; + +/** + * Summary metadata for the discussion body shown at the top of the transcript. + */ +export interface DiscussionTranscriptMeta { + id: string; + title: string; + url: string; + body: string; + author: string; +} + +/** + * A reply entry in the discussion transcript. + */ +export interface DiscussionTranscriptReply { + id: string; + body: string; + createdAt: string; + author: string; + replyToId: string; +} + +/** + * A top-level discussion comment with any nested replies. + */ +export interface DiscussionTranscriptComment extends DiscussionTranscriptReply { + replies: DiscussionTranscriptReply[]; +} + +/** + * Fetches one page of discussion comments and the first page of replies. + */ +function fetchDiscussionPage( + github: GraphQLClient, + owner: string, + repo: string, + number: number, + after?: string, +): DiscussionPagePayload { + return github.graphql( + ` + query($owner: String!, $repo: String!, $number: Int!, $after: String) { + repository(owner: $owner, name: $repo) { + discussion(number: $number) { + id + title + url + body + author { + login + } + comments(first: 100, after: $after) { + nodes { + id + body + createdAt + author { + login + } + replyTo { + id + } + replies(first: 100) { + nodes { + id + body + createdAt + author { + login + } + replyTo { + id + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + } + } + `, + { owner, repo, number, after }, + ); +} + +/** + * Fetches an additional page of replies for a single discussion comment. + */ +function fetchReplyPage( + github: GraphQLClient, + commentId: string, + after?: string, +): ReplyPagePayload { + return github.graphql( + ` + query($commentId: ID!, $after: String) { + node(id: $commentId) { + ... on DiscussionComment { + replies(first: 100, after: $after) { + nodes { + id + body + createdAt + author { + login + } + replyTo { + id + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + } + } + `, + { commentId, after }, + ); +} + +interface DiscussionPagePayload { + repository?: { + discussion?: { + id?: string; + title?: string; + url?: string; + body?: string; + author?: { login?: string | null } | null; + comments?: { + nodes?: Array<{ + id: string; + body?: string | null; + createdAt?: string | null; + author?: { login?: string | null } | null; + replyTo?: { id?: string | null } | null; + replies?: { + nodes?: Array<{ + id: string; + body?: string | null; + createdAt?: string | null; + author?: { login?: string | null } | null; + replyTo?: { id?: string | null } | null; + }>; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; + }>; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; + } | null; + } | null; +} + +interface ReplyPagePayload { + node?: { + replies?: { + nodes?: Array<{ + id: string; + body?: string | null; + createdAt?: string | null; + author?: { login?: string | null } | null; + replyTo?: { id?: string | null } | null; + }>; + pageInfo?: { + hasNextPage?: boolean | null; + endCursor?: string | null; + } | null; + } | null; + } | null; +} + +function normalizeReply(reply: { + id: string; + body?: string | null; + createdAt?: string | null; + author?: { login?: string | null } | null; + replyTo?: { id?: string | null } | null; +}): DiscussionTranscriptReply { + return { + id: reply.id, + body: reply.body || "", + createdAt: reply.createdAt || "", + author: reply.author?.login || "ghost", + replyToId: reply.replyTo?.id || "", + }; +} + +/** + * Fetches the full discussion transcript, including paginated comments and replies. + */ +export function fetchDiscussionTranscript( + github: GraphQLClient, + owner: string, + repo: string, + number: number, +): { + discussionMeta: DiscussionTranscriptMeta; + comments: DiscussionTranscriptComment[]; +} { + let discussionMeta: DiscussionTranscriptMeta | null = null; + const comments: DiscussionTranscriptComment[] = []; + let after: string | undefined; + let hasNextPage = true; + + while (hasNextPage) { + const page = fetchDiscussionPage(github, owner, repo, number, after); + const discussion = page.repository?.discussion; + if (!discussion) { + throw new Error(`Discussion #${number} not found`); + } + + if (!discussionMeta) { + discussionMeta = { + id: discussion.id || "", + title: discussion.title || "", + url: discussion.url || "", + body: discussion.body || "", + author: discussion.author?.login || "ghost", + }; + } + + for (const rawComment of discussion.comments?.nodes || []) { + const replies = (rawComment.replies?.nodes || []).map(normalizeReply); + let replyAfter = rawComment.replies?.pageInfo?.endCursor || undefined; + let replyHasNextPage = rawComment.replies?.pageInfo?.hasNextPage || false; + + while (replyHasNextPage) { + const replyPage = fetchReplyPage(github, rawComment.id, replyAfter); + const moreReplies = replyPage.node?.replies; + if (!moreReplies) { + break; + } + + replies.push(...(moreReplies.nodes || []).map(normalizeReply)); + replyAfter = moreReplies.pageInfo?.endCursor || undefined; + replyHasNextPage = moreReplies.pageInfo?.hasNextPage || false; + } + + comments.push({ + ...normalizeReply(rawComment), + replies, + }); + } + + after = discussion.comments?.pageInfo?.endCursor || undefined; + hasNextPage = discussion.comments?.pageInfo?.hasNextPage || false; + } + + return { + discussionMeta: discussionMeta || { + id: "", + title: "", + url: "", + body: "", + author: "ghost", + }, + comments, + }; +} + +/** + * Builds the markdown transcript consumed by the agent prompt. + */ +export function buildDiscussionTranscript( + discussionMeta: DiscussionTranscriptMeta, + comments: DiscussionTranscriptComment[], +): string { + let transcript = "# Discussion\n\n"; + transcript += `Title: ${discussionMeta.title}\n`; + transcript += `URL: ${discussionMeta.url}\n`; + transcript += `Author: ${discussionMeta.author}\n\n`; + transcript += `## Body\n${discussionMeta.body}\n\n`; + transcript += "## Comments\n\n"; + + if (comments.length === 0) { + transcript += "_No comments yet._\n"; + return transcript; + } + + for (const comment of comments) { + transcript += formatDiscussionTranscriptComment(comment, 0); + transcript += "\n"; + for (const reply of comment.replies) { + transcript += formatDiscussionTranscriptComment(reply, 1); + transcript += "\n"; + } + } + + return transcript; +} + +/** + * Formats a top-level comment or nested reply for the transcript body. + */ +export function formatDiscussionTranscriptComment( + comment: DiscussionTranscriptReply, + depth: number, +): string { + const heading = depth === 0 ? "### Comment" : "#### Reply"; + const author = comment.author || "ghost"; + const createdAt = comment.createdAt || ""; + return `${heading} by ${author} at ${createdAt}\n${comment.body || ""}\n`; +} diff --git a/.agent/src/discussion.ts b/.agent/src/discussion.ts new file mode 100644 index 0000000..e20df49 --- /dev/null +++ b/.agent/src/discussion.ts @@ -0,0 +1,353 @@ +// Discussion-specific GraphQL operations needed by the portal. +// +// Uses gh api graphql for all calls, consistent with the self-serve pattern. + +import { + createGhGraphqlClient, + ghGraphqlData, + type GraphQLClient, +} from "./github-graphql.js"; + +export interface DiscussionComment { + id: string; + body: string; + created_at: string; +} + +export interface DiscussionCategory { + id: string; + name: string; +} + +export interface RepositoryDiscussionConfig { + repositoryId: string; + hasDiscussionsEnabled: boolean; + categories: DiscussionCategory[]; +} + +export interface RepositoryDiscussionSummary { + id: string; + number: number; + title: string; + url: string; + category: string; +} + +/** + * Resolves the reply-to target for a discussion comment. + * Returns the parent comment node ID if the comment is a nested reply, + * or the comment's own ID if it's a top-level reply. + */ +export function resolveDiscussionReplyTo(commentNodeId: string): string { + const query = ` + query($nodeId: ID!) { + node(id: $nodeId) { + ... on DiscussionComment { + replyTo { id } + } + } + } + `; + const data = ghGraphqlData<{ node?: { replyTo?: { id: string } | null } }>( + query, + { nodeId: commentNodeId }, + ); + // If the comment has a replyTo, it's a nested reply — use the parent. + // Otherwise return the comment itself as the reply target. + return data.node?.replyTo?.id || commentNodeId; +} + +/** + * Fetches all comments for a discussion with cursor-based pagination. + * Returns flattened list suitable for findLatestPendingRequest scanning. + */ +export function fetchDiscussionComments( + owner: string, + repo: string, + number: number, +): DiscussionComment[] { + const query = ` + query($owner: String!, $repo: String!, $number: Int!, $cursor: String) { + repository(owner: $owner, name: $repo) { + discussion(number: $number) { + comments(first: 100, after: $cursor) { + pageInfo { + hasNextPage + endCursor + } + nodes { + id + body + createdAt + } + } + } + } + } + `; + + const allComments: DiscussionComment[] = []; + let cursor = ""; + let hasNextPage = true; + + while (hasNextPage) { + const vars: { + owner: string; + repo: string; + number: number; + cursor?: string; + } = { + owner, + repo, + number, + }; + if (cursor) { + vars.cursor = cursor; + } + + const data = ghGraphqlData<{ + repository?: { + discussion?: { + comments?: { + pageInfo?: { hasNextPage?: boolean; endCursor?: string | null }; + nodes?: Array<{ id: string; body: string; createdAt: string }>; + }; + }; + }; + }>(query, vars); + + const comments = data.repository?.discussion?.comments; + const nodes = comments?.nodes || []; + for (const n of nodes) { + allComments.push({ + id: n.id, + body: n.body || "", + created_at: n.createdAt || "", + }); + } + + hasNextPage = comments?.pageInfo?.hasNextPage ?? false; + cursor = comments?.pageInfo?.endCursor || ""; + } + + return allComments; +} + +/** + * Updates an existing discussion comment body. + */ +export function updateDiscussionComment( + commentId: string, + body: string, +): void { + const query = ` + mutation($commentId: ID!, $body: String!) { + updateDiscussionComment(input: { commentId: $commentId, body: $body }) { + comment { id } + } + } + `; + ghGraphqlData<{ + updateDiscussionComment?: { comment?: { id?: string } | null } | null; + }>(query, { commentId, body }); +} + +export function addDiscussionComment(discussionId: string, body: string): string { + const query = ` + mutation($discussionId: ID!, $body: String!) { + addDiscussionComment(input: { discussionId: $discussionId, body: $body }) { + comment { url } + } + } + `; + const data = ghGraphqlData<{ + addDiscussionComment?: { comment?: { url?: string } | null } | null; + }>(query, { discussionId, body }); + const url = data.addDiscussionComment?.comment?.url || ""; + if (!url) { + throw new Error("GitHub did not return a URL for the discussion comment."); + } + return url; +} + +export function findRepositoryDiscussionByTitle( + owner: string, + repo: string, + title: string, + categoryName = "", + client: GraphQLClient = createGhGraphqlClient(), +): RepositoryDiscussionSummary | null { + const query = ` + query($owner: String!, $repo: String!) { + repository(owner: $owner, name: $repo) { + discussions(first: 50, orderBy: { field: UPDATED_AT, direction: DESC }) { + nodes { + id + number + title + url + category { name } + } + } + } + } + `; + const data = client.graphql<{ + repository?: { + discussions?: { + nodes?: Array<{ + id?: string; + number?: number; + title?: string; + url?: string; + category?: { name?: string | null } | null; + } | null> | null; + } | null; + } | null; + }>(query, { owner, repo }); + + for (const node of data.repository?.discussions?.nodes || []) { + const nodeTitle = node?.title || ""; + const category = node?.category?.name || ""; + if ( + node?.id && + Number.isInteger(node.number) && + nodeTitle === title && + (!categoryName || category === categoryName) + ) { + return { + id: node.id, + number: node.number as number, + title: nodeTitle, + url: node.url || "", + category, + }; + } + } + + return null; +} + +/** + * Fetches repository discussion settings and all visible discussion categories. + */ +export function fetchRepositoryDiscussionConfig( + client: GraphQLClient, + owner: string, + repo: string, +): RepositoryDiscussionConfig { + const query = ` + query($owner: String!, $repo: String!, $cursor: String) { + repository(owner: $owner, name: $repo) { + id + hasDiscussionsEnabled + discussionCategories(first: 100, after: $cursor) { + pageInfo { hasNextPage endCursor } + nodes { id name } + } + } + } + `; + + const categories: DiscussionCategory[] = []; + let repositoryId = ""; + let hasDiscussionsEnabled = false; + let cursor = ""; + let hasNextPage = true; + + while (hasNextPage) { + const variables: { owner: string; repo: string; cursor?: string } = { owner, repo }; + if (cursor) variables.cursor = cursor; + + const data = client.graphql<{ + repository?: { + id?: string; + hasDiscussionsEnabled?: boolean; + discussionCategories?: { + pageInfo?: { hasNextPage?: boolean; endCursor?: string | null } | null; + nodes?: Array<{ id?: string; name?: string } | null> | null; + } | null; + } | null; + }>(query, variables); + + const repository = data.repository; + if (!repository?.id) { + throw new Error(`Repository not found: ${owner}/${repo}`); + } + + repositoryId = repository.id; + hasDiscussionsEnabled = repository.hasDiscussionsEnabled ?? false; + + const page = repository.discussionCategories; + for (const category of page?.nodes || []) { + if (category?.id && category.name) { + categories.push({ id: category.id, name: category.name }); + } + } + + hasNextPage = page?.pageInfo?.hasNextPage ?? false; + cursor = page?.pageInfo?.endCursor || ""; + } + + return { repositoryId, hasDiscussionsEnabled, categories }; +} + +export function requireDiscussionCategory( + config: RepositoryDiscussionConfig, + categoryName: string, +): DiscussionCategory { + if (!config.hasDiscussionsEnabled) { + throw new Error("Repository discussions are not enabled; cannot create a discussion."); + } + + const category = config.categories.find((candidate) => candidate.name === categoryName); + if (!category) { + throw new Error(`Required discussion category '${categoryName}' was not found.`); + } + + return category; +} + +export function createDiscussion( + client: GraphQLClient, + repoId: string, + categoryId: string, + title: string, + body: string, +): { url: string } { + const query = ` + mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) { + createDiscussion(input: { + repositoryId: $repoId, + categoryId: $categoryId, + title: $title, + body: $body + }) { + discussion { url } + } + } + `; + + const data = client.graphql<{ + createDiscussion?: { discussion?: { url?: string } | null } | null; + }>(query, { repoId, categoryId, title, body }); + + const url = data.createDiscussion?.discussion?.url; + if (!url) { + throw new Error("GitHub did not return a URL for the created discussion."); + } + return { url }; +} + +export function createRepositoryDiscussion( + owner: string, + repo: string, + categoryName: string, + title: string, + body: string, + client: GraphQLClient = createGhGraphqlClient(), +): { url: string } { + const config = fetchRepositoryDiscussionConfig(client, owner, repo); + const category = requireDiscussionCategory(config, categoryName); + return createDiscussion(client, config.repositoryId, category.id, title, body); +} diff --git a/.agent/src/envelope.ts b/.agent/src/envelope.ts new file mode 100644 index 0000000..b357c84 --- /dev/null +++ b/.agent/src/envelope.ts @@ -0,0 +1,202 @@ +// Runtime envelope: the shared metadata contract that every agent route +// receives. Agents use this identity block plus self-serve tool calls +// (gh, git, local file reads) to gather the context they need. + +export interface RuntimeEnvelope { + schema_version: number; + repo_slug: string; + route: string; + source_kind: string; + target_kind: string; + target_number: number; + target_url: string; + request_text: string; + requested_by: string; + approval_comment_url: string | null; + workflow: string; + lane: string; + thread_key: string; +} + +export interface EventContext { + body: string; + sourceKind: string; + targetKind: string; + targetNumber: string; + targetUrl: string; +} + +export interface RuntimeParams { + repo_slug: string; + route: string; + requested_by: string; + approval_comment_url?: string | null; + workflow?: string; + lane?: string; +} + +export interface EnvelopeParams { + repo_slug: string; + route: string; + source_kind: string; + target_kind: string; + target_number: number; + target_url: string; + request_text?: string; + requested_by: string; + approval_comment_url?: string | null; + workflow?: string; + lane?: string; +} + +export const SCHEMA_VERSION = 1; +export const DEFAULT_LANE = "default"; + +export const VALID_ROUTES = new Set([ + "review", + "implement", + "fix-pr", + "answer", + "create-action", + "dispatch", + "orchestrator", + "agent-self-approve", + "agent-self-merge", + "skill", + "rubrics-review", + "rubrics-initialization", + "rubrics-update", +]); + +export const VALID_SOURCE_KINDS = new Set([ + "issue", + "issue_comment", + "pull_request", + "pull_request_review_comment", + "pull_request_review", + "discussion", + "discussion_comment", + "workflow_dispatch", +]); + +export const VALID_TARGET_KINDS = new Set(["issue", "pull_request", "discussion", "repository"]); + +export const REQUIRED_FIELDS = [ + "repo_slug", + "route", + "source_kind", + "target_kind", + "target_number", + "target_url", + "requested_by", +] as const; + +export function buildThreadKey(params: { + repo_slug: string; + target_kind: string; + target_number: number; + route: string; + lane?: string; +}): string { + const effectiveLane = String(params.lane || DEFAULT_LANE); + return `${params.repo_slug}:${params.target_kind}:${params.target_number}:${params.route}:${effectiveLane}`; +} + +export function buildEnvelope(params: EnvelopeParams): RuntimeEnvelope { + const envelope: RuntimeEnvelope = { + schema_version: SCHEMA_VERSION, + repo_slug: String(params.repo_slug || ""), + route: String(params.route || ""), + source_kind: String(params.source_kind || ""), + target_kind: String(params.target_kind || ""), + target_number: Number(params.target_number) || 0, + target_url: String(params.target_url || ""), + request_text: String(params.request_text || ""), + requested_by: String(params.requested_by || ""), + approval_comment_url: params.approval_comment_url || null, + workflow: String(params.workflow || ""), + lane: String(params.lane || DEFAULT_LANE), + thread_key: "", + }; + + envelope.thread_key = buildThreadKey(envelope); + return envelope; +} + +export function validateEnvelope(envelope: RuntimeEnvelope | null | undefined): string[] { + const errors: string[] = []; + + if (!envelope || typeof envelope !== "object") { + return ["Envelope must be a non-null object"]; + } + + if (envelope.schema_version !== SCHEMA_VERSION) { + errors.push( + `Unsupported schema_version: ${envelope.schema_version} (expected ${SCHEMA_VERSION})` + ); + } + + for (const field of REQUIRED_FIELDS) { + const value = (envelope as unknown as Record)[field]; + // Repository-scoped runs (scan, sync) have no target_number; 0 is valid. + const allowZeroTargetNumber = field === "target_number" && envelope.target_kind === "repository"; + if ( + value === undefined || + value === null || + value === "" || + (typeof value === "number" && value === 0 && !allowZeroTargetNumber) + ) { + errors.push(`Missing required field: ${field}`); + } + } + + if (envelope.route && !VALID_ROUTES.has(envelope.route)) { + errors.push(`Invalid route: ${envelope.route}`); + } + + if (envelope.source_kind && !VALID_SOURCE_KINDS.has(envelope.source_kind)) { + errors.push(`Invalid source_kind: ${envelope.source_kind}`); + } + + if (envelope.target_kind && !VALID_TARGET_KINDS.has(envelope.target_kind)) { + errors.push(`Invalid target_kind: ${envelope.target_kind}`); + } + + return errors; +} + +export function buildEnvelopeFromEventContext( + eventContext: EventContext, + runtime: RuntimeParams +): RuntimeEnvelope { + return buildEnvelope({ + repo_slug: runtime.repo_slug, + route: runtime.route, + source_kind: eventContext.sourceKind, + target_kind: eventContext.targetKind, + target_number: Number(eventContext.targetNumber), + target_url: eventContext.targetUrl, + request_text: eventContext.body, + requested_by: runtime.requested_by, + approval_comment_url: runtime.approval_comment_url || null, + workflow: runtime.workflow, + lane: runtime.lane, + }); +} + +export function envelopeToPromptVars(envelope: RuntimeEnvelope): Record { + return { + REPO_SLUG: envelope.repo_slug, + ROUTE: envelope.route, + SOURCE_KIND: envelope.source_kind, + TARGET_KIND: envelope.target_kind, + TARGET_NUMBER: String(envelope.target_number), + TARGET_URL: envelope.target_url, + REQUEST_TEXT: envelope.request_text, + MENTION_BODY: envelope.request_text, + REQUESTED_BY: envelope.requested_by, + WORKFLOW: envelope.workflow, + LANE: envelope.lane, + THREAD_KEY: envelope.thread_key, + }; +} diff --git a/.agent/src/fix-pr-status.ts b/.agent/src/fix-pr-status.ts new file mode 100644 index 0000000..b9a9c06 --- /dev/null +++ b/.agent/src/fix-pr-status.ts @@ -0,0 +1,19 @@ +export const FIX_PR_STATUS_MARKER = ""; + +const FIX_PR_STATUS_PATTERNS = [ + /\*\*Sepo pushed fixes for this PR\.\*\*/, + /\*\*Sepo did not produce code changes for this PR\.\*\*/, + /\*\*Sepo could not update this PR automatically\.\*\*/, + /\*\*Sepo could not complete the PR fix run\.\*\*/, + /\*\*Sepo made changes, but lightweight verification failed\.\*\*[\s\S]*Inspect the workflow logs before retrying the PR fix run\./, +]; + +export function buildFixPrStatusMarker(): string { + return FIX_PR_STATUS_MARKER; +} + +export function isFixPrStatusBody(body: string): boolean { + const value = String(body || ""); + return value.includes(FIX_PR_STATUS_MARKER) || + FIX_PR_STATUS_PATTERNS.some((pattern) => pattern.test(value)); +} diff --git a/.agent/src/git.ts b/.agent/src/git.ts new file mode 100644 index 0000000..18730da --- /dev/null +++ b/.agent/src/git.ts @@ -0,0 +1,192 @@ +// Git helpers for workflow post-processing steps. +// +// These functions wrap the git CLI operations that workflows perform after +// the agent completes: branch management, committing, and pushing. +// +// The low-level `git()` runner and `buildAuthUrl()` are also used by +// thread-state-git.ts for ref-based state storage. + +import { execFileSync } from "node:child_process"; + +const DEFAULT_BOT_NAME = "sepo-agent"; +const DEFAULT_BOT_EMAIL = "279869237+sepo-agent@users.noreply.github.com"; +const GIT_MAX_BUFFER = 10 * 1024 * 1024; // 10 MB + +/** Excluded patterns for git add (secrets, private keys). */ +const ADD_EXCLUDES = [":!.env*", ":!*.pem", ":!*.key"]; + +// --------------------------------------------------------------------------- +// Low-level primitives (shared across modules) +// --------------------------------------------------------------------------- + +/** + * Runs a git command synchronously and returns trimmed stdout. + * Accepts optional stdin input for commands like `hash-object --stdin` + * and `mktree`. + */ +export function git( + args: string[], + cwd: string, + input?: string, +): string { + return execFileSync("git", args, { + cwd, + input, + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: GIT_MAX_BUFFER, + }).toString("utf8").trim(); +} + +/** + * Builds an authenticated HTTPS remote URL for pushing. + * Used by branch push helpers and thread-state ref pushes. + */ +export function buildAuthUrl(token: string, repo: string): string { + return `https://x-access-token:${token}@github.com/${repo}.git`; +} + +export function configureBotIdentity(cwd: string, name?: string, email?: string): void { + const botName = name || process.env.GIT_BOT_NAME || DEFAULT_BOT_NAME; + const botEmail = email || process.env.GIT_BOT_EMAIL || DEFAULT_BOT_EMAIL; + execFileSync("git", ["config", "user.name", botName], { cwd, stdio: "pipe" }); + execFileSync("git", ["config", "user.email", botEmail], { cwd, stdio: "pipe" }); +} + +export function createBranch(baseBranch: string, branchName: string, cwd: string): void { + execFileSync("git", ["checkout", "-b", branchName, baseBranch], { cwd, stdio: "pipe" }); +} + +export function hasChanges(cwd: string): boolean { + const output = execFileSync("git", ["status", "--porcelain"], { cwd, stdio: "pipe" }) + .toString("utf8") + .trim(); + return output.length > 0; +} + +export function currentHead(cwd: string): string { + return git(["rev-parse", "HEAD"], cwd); +} + +export function hasHeadChanged(originalHead: string, cwd: string): boolean { + return Boolean(originalHead) && currentHead(cwd) !== originalHead; +} + +export function hasStagedChanges(cwd: string): boolean { + try { + execFileSync("git", ["diff", "--cached", "--quiet"], { cwd, stdio: "pipe" }); + return false; + } catch { + return true; + } +} + +export function stageAll(cwd: string): void { + execFileSync("git", ["add", "-A", "--", ...ADD_EXCLUDES], { cwd, stdio: "pipe" }); +} + +export function commit(message: string, cwd: string): void { + execFileSync("git", ["commit", "-m", message], { cwd, stdio: "pipe" }); +} + +export function pushBranch( + branch: string, + token: string, + repo: string, + cwd: string, + opts?: { setUpstream?: boolean }, +): void { + const url = buildAuthUrl(token, repo); + const args = ["push"]; + if (opts?.setUpstream) args.push("-u"); + args.push(url, branch); + execFileSync("git", args, { cwd, stdio: "pipe" }); +} + +export function buildPushToRefArgs( + remoteUrl: string, + headRef: string, + opts?: { forceWithLeaseOid?: string }, +): string[] { + const args = ["push"]; + if (opts?.forceWithLeaseOid) { + args.push(`--force-with-lease=refs/heads/${headRef}:${opts.forceWithLeaseOid}`); + } + args.push(remoteUrl, `HEAD:${headRef}`); + return args; +} + +export function pushToRef( + headRef: string, + token: string, + repo: string, + cwd: string, + opts?: { forceWithLeaseOid?: string }, +): void { + const url = buildAuthUrl(token, repo); + execFileSync("git", buildPushToRefArgs(url, headRef, opts), { cwd, stdio: "pipe" }); +} + +export function cleanupBranch( + branchName: string, + baseBranch: string, + cwd: string, +): void { + try { execFileSync("git", ["checkout", "-f", baseBranch], { cwd, stdio: "pipe" }); } catch { /* ok */ } + try { execFileSync("git", ["branch", "-D", branchName], { cwd, stdio: "pipe" }); } catch { /* ok */ } + try { execFileSync("git", ["reset", "--hard", "HEAD"], { cwd, stdio: "pipe" }); } catch { /* ok */ } + try { execFileSync("git", ["clean", "-fd"], { cwd, stdio: "pipe" }); } catch { /* ok */ } +} + +export function cleanupWorktree(baseBranch: string, cwd: string): void { + try { execFileSync("git", ["reset", "--hard", "HEAD"], { cwd, stdio: "pipe" }); } catch { /* ok */ } + try { execFileSync("git", ["clean", "-fd"], { cwd, stdio: "pipe" }); } catch { /* ok */ } + try { execFileSync("git", ["checkout", "-f", baseBranch], { cwd, stdio: "pipe" }); } catch { /* ok */ } +} + +export interface CommitAndPushResult { + committed: boolean; + branch: string; +} + +/** + * Stages, commits, and pushes changes. Returns whether a commit was made. + * Skips if there are no staged changes after git add. + */ +export function commitAndPush(opts: { + message: string; + branch: string; + token: string; + repo: string; + cwd: string; + setUpstream?: boolean; + pushRef?: string; + pushLeaseOid?: string; +}): CommitAndPushResult { + stageAll(opts.cwd); + if (!hasStagedChanges(opts.cwd)) { + return { committed: false, branch: opts.branch }; + } + commit(opts.message, opts.cwd); + if (opts.pushRef) { + pushToRef(opts.pushRef, opts.token, opts.repo, opts.cwd, { + forceWithLeaseOid: opts.pushLeaseOid, + }); + } else { + pushBranch(opts.branch, opts.token, opts.repo, opts.cwd, { + setUpstream: opts.setUpstream, + }); + } + return { committed: true, branch: opts.branch }; +} + +export function pushHeadUpdate(opts: { + branch: string; + token: string; + repo: string; + cwd: string; + expectedHead: string; +}): void { + pushToRef(opts.branch, opts.token, opts.repo, opts.cwd, { + forceWithLeaseOid: opts.expectedHead, + }); +} diff --git a/.agent/src/github-graphql.ts b/.agent/src/github-graphql.ts new file mode 100644 index 0000000..3178ebb --- /dev/null +++ b/.agent/src/github-graphql.ts @@ -0,0 +1,67 @@ +import { execFileSync } from "node:child_process"; + +export type GraphQLVariableValue = + | string + | number + | boolean + | null + | undefined; + +const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024; + +export interface GraphQLClient { + graphql( + query: string, + variables: Record, + ): T; +} + +/** + * Calls `gh api graphql` and returns the decoded `data` payload. + */ +export function ghGraphqlData( + query: string, + variables: Record, + options: { maxBuffer?: number } = {}, +): T { + const args = ["api", "graphql", "-f", `query=${query}`]; + for (const [key, value] of Object.entries(variables)) { + if (typeof value === "number" || typeof value === "boolean") { + args.push("-F", `${key}=${value}`); + } else if (value != null) { + args.push("-f", `${key}=${value}`); + } + } + + const stdout = execFileSync("gh", args, { + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER, + }).toString("utf8"); + const payload = JSON.parse(stdout) as { + data?: T; + errors?: Array<{ message?: string }>; + }; + + if (Array.isArray(payload.errors) && payload.errors.length > 0) { + const messages = payload.errors + .map((error) => error?.message || JSON.stringify(error)) + .join("; "); + throw new Error(`gh api graphql returned errors: ${messages}`); + } + + if (payload.data === undefined) { + throw new Error("gh api graphql returned no data"); + } + + return payload.data; +} + +export function createGhGraphqlClient( + options: { maxBuffer?: number } = {}, +): GraphQLClient { + return { + graphql(query: string, variables: Record): T { + return ghGraphqlData(query, variables, options); + }, + }; +} diff --git a/.agent/src/github.ts b/.agent/src/github.ts new file mode 100644 index 0000000..1e49b1e --- /dev/null +++ b/.agent/src/github.ts @@ -0,0 +1,507 @@ +// GitHub API helpers for workflow post-processing steps. +// +// These functions wrap gh CLI operations that workflows perform: posting +// comments, creating PRs, fetching metadata, dispatching workflows. + +import { execFileSync } from "node:child_process"; + +export const MAX_BUFFER = 10 * 1024 * 1024; + +export function gh(args: string[], cwd?: string): string { + return execFileSync("gh", args, { + cwd, + stdio: "pipe", + maxBuffer: MAX_BUFFER, + }).toString("utf8"); +} + +/** + * Runs `gh api ` and returns trimmed stdout. Returns "" on any + * non-zero exit. Use for best-effort lookups where a 404 is an expected + * answer (e.g. "is this user a collaborator?"). + */ +export function ghApi(args: string[]): string { + try { + return gh(["api", ...args]).trim(); + } catch { + return ""; + } +} + +/** + * Returns true if `gh api ` exits 0. Use for endpoints that return + * 204 on success (no body) and 404 on absence, where `ghApi` can't + * distinguish the two. + */ +export function ghApiOk(args: string[]): boolean { + try { + gh(["api", ...args]); + return true; + } catch { + return false; + } +} + +// --- Comments --- + +export function postIssueComment(issueNumber: number, body: string, repo?: string): void { + const args = ["issue", "comment", String(issueNumber), "--body", body]; + if (repo) args.push("--repo", repo); + gh(args); +} + +export function postPrComment(prNumber: number, body: string, repo?: string): void { + const args = ["pr", "comment", String(prNumber), "--body", body]; + if (repo) args.push("--repo", repo); + gh(args); +} + +export function updateIssueComment(repo: string, commentId: string | number, body: string): void { + gh([ + "api", + "--method", + "PATCH", + `repos/${repo}/issues/comments/${commentId}`, + "-f", + `body=${body}`, + ]); +} + +// --- Labels --- + +export interface EnsureLabelOptions { + name: string; + color: string; + description: string; + repo?: string; +} + +function commandErrorText(err: unknown): string { + const record = err as { message?: unknown; stderr?: unknown; stdout?: unknown }; + return [record.message, record.stderr, record.stdout] + .map((part) => { + if (Buffer.isBuffer(part)) return part.toString("utf8"); + return typeof part === "string" ? part : ""; + }) + .filter(Boolean) + .join("\n"); +} + +function isAlreadyExistsLabelError(err: unknown): boolean { + return /already exists|already_exists|name has already been taken/i.test(commandErrorText(err)); +} + +export function ensureLabel(opts: EnsureLabelOptions): void { + const name = opts.name.trim(); + if (!name) return; + + const listArgs = ["label", "list", "--search", name, "--json", "name", "--jq", ".[].name"]; + if (opts.repo) listArgs.push("--repo", opts.repo); + + const existing = gh(listArgs) + .split(/\r?\n/) + .some((line) => line.trim() === name); + if (existing) return; + + const createArgs = [ + "label", + "create", + name, + "--color", + opts.color, + "--description", + opts.description, + ]; + if (opts.repo) createArgs.push("--repo", opts.repo); + + try { + gh(createArgs); + } catch (err: unknown) { + if (!isAlreadyExistsLabelError(err)) throw err; + } +} + +export function addIssueLabel(issueNumber: number, label: string, repo?: string): void { + const args = ["issue", "edit", String(issueNumber), "--add-label", label]; + if (repo) args.push("--repo", repo); + gh(args); +} + +export function addPrLabel(prNumber: number, label: string, repo?: string): void { + const args = ["pr", "edit", String(prNumber), "--add-label", label]; + if (repo) args.push("--repo", repo); + gh(args); +} + +export function removeIssueLabel(issueNumber: number, label: string, repo?: string): void { + const args = ["issue", "edit", String(issueNumber), "--remove-label", label]; + if (repo) args.push("--repo", repo); + gh(args); +} + +export function removePrLabel(prNumber: number, label: string, repo?: string): void { + const args = ["pr", "edit", String(prNumber), "--remove-label", label]; + if (repo) args.push("--repo", repo); + gh(args); +} + +// --- Pull requests --- + +export interface PrMeta { + headRef: string; + headOid: string; + isCrossRepository: boolean; + state: string; +} + +export interface IssueCommentRecord { + id: string; + body: string; + authorLogin: string; + createdAt: string; +} + +export interface PrStatusCheckRecord { + name: string; + status: string; + conclusion: string; + state: string; +} + +export interface PrMergeMeta { + headOid: string; + isDraft: boolean; + state: string; + mergeStateStatus: string; + mergeable: string; + reviewDecision: string; + autoMergeRequestExists: boolean; + statusChecks: PrStatusCheckRecord[]; +} + +export interface PrReviewRecord { + id: string; + body: string; + state: string; + authorLogin: string; + commitId: string; + submittedAt: string; +} + +function extractLogin(value: unknown): string { + if (!value || typeof value !== "object" || Array.isArray(value)) return ""; + const login = (value as Record).login; + return typeof login === "string" ? login.trim() : ""; +} + +function authorLoginFromRecord(record: Record): string { + return extractLogin(record.author) || extractLogin(record.user); +} + +function normalizeActorLogin(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/^app\//i, "") + .replace(/\[bot\]$/i, ""); +} + +function createdAtMs(value: string): number { + const parsed = Date.parse(String(value || "")); + return Number.isFinite(parsed) ? parsed : 0; +} + +export function fetchPrMeta(prNumber: number, repo?: string): PrMeta { + const args = ["pr", "view", String(prNumber), "--json", "headRefName,headRefOid,isCrossRepository,state"]; + if (repo) args.push("--repo", repo); + const data = JSON.parse(gh(args)); + return { + headRef: String(data.headRefName ?? ""), + headOid: String(data.headRefOid ?? ""), + isCrossRepository: Boolean(data.isCrossRepository), + state: String(data.state ?? ""), + }; +} + +function normalizePrStatusCheckRecord(value: unknown): PrStatusCheckRecord | null { + if (!value || typeof value !== "object" || Array.isArray(value)) return null; + const record = value as Record; + return { + name: String(record.name ?? record.context ?? record.workflowName ?? ""), + status: String(record.status ?? ""), + conclusion: String(record.conclusion ?? ""), + state: String(record.state ?? ""), + }; +} + +export function fetchPrMergeMeta(prNumber: number, repo?: string): PrMergeMeta { + const args = [ + "pr", + "view", + String(prNumber), + "--json", + "headRefOid,isDraft,state,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,autoMergeRequest", + ]; + if (repo) args.push("--repo", repo); + const data = JSON.parse(gh(args)) as Record; + const statusCheckRollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : []; + return { + headOid: String(data.headRefOid ?? ""), + isDraft: Boolean(data.isDraft), + state: String(data.state ?? ""), + mergeStateStatus: String(data.mergeStateStatus ?? ""), + mergeable: String(data.mergeable ?? ""), + reviewDecision: String(data.reviewDecision ?? ""), + autoMergeRequestExists: Boolean(data.autoMergeRequest), + statusChecks: statusCheckRollup + .map(normalizePrStatusCheckRecord) + .filter((check): check is PrStatusCheckRecord => Boolean(check)), + }; +} + +export function fetchAuthenticatedActorLogin(): string { + const raw = gh([ + "api", + "graphql", + "-f", + "query=query ViewerLogin { viewer { login } }", + ]).trim(); + const parsed = JSON.parse(raw || "{}") as { + data?: { viewer?: { login?: unknown } | null } | null; + viewer?: { login?: unknown } | null; + }; + return String(parsed.data?.viewer?.login || parsed.viewer?.login || "").trim(); +} + +export function fetchPrAuthorLogin(prNumber: number, repo?: string): string { + const args = ["pr", "view", String(prNumber), "--json", "author"]; + if (repo) args.push("--repo", repo); + const data = JSON.parse(gh(args)) as Record; + return authorLoginFromRecord(data); +} + +function normalizePrReviewRecord(value: unknown): PrReviewRecord | null { + if (!value || typeof value !== "object" || Array.isArray(value)) return null; + const record = value as Record; + return { + id: String(record.id || ""), + body: String(record.body || ""), + state: String(record.state || ""), + authorLogin: authorLoginFromRecord(record), + commitId: String(record.commit_id ?? record.commitId ?? ""), + submittedAt: String(record.submitted_at ?? record.submittedAt ?? ""), + }; +} + +export function fetchPrReviewRecords(prNumber: number, repo: string): PrReviewRecord[] { + const raw = gh([ + "api", + "--paginate", + "--slurp", + `repos/${repo}/pulls/${prNumber}/reviews`, + ]).trim(); + if (!raw) return []; + + const parsed = JSON.parse(raw) as unknown; + const pages = Array.isArray(parsed) ? parsed : [parsed]; + const reviews: PrReviewRecord[] = []; + for (const page of pages) { + const entries = Array.isArray(page) ? page : [page]; + for (const entry of entries) { + const review = normalizePrReviewRecord(entry); + if (review) reviews.push(review); + } + } + return reviews; +} + +function requireMatchHeadCommit(matchHeadCommit: string): string { + const trimmed = String(matchHeadCommit || "").trim(); + if (!trimmed) throw new Error("match head commit is required"); + return trimmed; +} + +export function markPullRequestReady(prNumber: number, repo: string): void { + gh(["pr", "ready", String(prNumber), "--repo", repo]); +} + +export function mergePullRequest(prNumber: number, repo: string, matchHeadCommit: string): void { + gh([ + "pr", + "merge", + String(prNumber), + "--repo", + repo, + "--merge", + "--match-head-commit", + requireMatchHeadCommit(matchHeadCommit), + ]); +} + +export function enablePullRequestAutoMerge(prNumber: number, repo: string, matchHeadCommit: string): void { + gh([ + "pr", + "merge", + String(prNumber), + "--repo", + repo, + "--merge", + "--auto", + "--match-head-commit", + requireMatchHeadCommit(matchHeadCommit), + ]); +} + +function normalizeIssueCommentRecord(value: unknown): IssueCommentRecord | null { + if (!value || typeof value !== "object" || Array.isArray(value)) return null; + const record = value as Record; + return { + id: String(record.id || ""), + body: String(record.body || ""), + authorLogin: authorLoginFromRecord(record), + createdAt: String(record.created_at ?? record.createdAt ?? ""), + }; +} + +export function fetchIssueCommentRecords(issueNumber: number, repo: string): IssueCommentRecord[] { + const raw = gh([ + "api", + "--paginate", + "--slurp", + `repos/${repo}/issues/${issueNumber}/comments`, + ]).trim(); + if (!raw) return []; + + const parsed = JSON.parse(raw) as unknown; + const pages = Array.isArray(parsed) ? parsed : [parsed]; + const comments: IssueCommentRecord[] = []; + for (const page of pages) { + const entries = Array.isArray(page) ? page : [page]; + for (const entry of entries) { + const comment = normalizeIssueCommentRecord(entry); + if (comment) comments.push(comment); + } + } + return comments; +} + +export function upsertPrCommentByMarker( + prNumber: number, + repo: string, + marker: string, + body: string, +): "created" | "updated" { + const trustedActor = normalizeActorLogin(fetchAuthenticatedActorLogin()); + const existing = fetchIssueCommentRecords(prNumber, repo) + .filter((comment) => ( + comment.id && + comment.body.includes(marker) && + trustedActor && + normalizeActorLogin(comment.authorLogin) === trustedActor + )) + .sort((left, right) => createdAtMs(left.createdAt) - createdAtMs(right.createdAt)); + const latest = existing[existing.length - 1]; + if (latest) { + updateIssueComment(repo, latest.id, body); + return "updated"; + } + + postPrComment(prNumber, body, repo); + return "created"; +} + +export function findExistingPr(headBranch: string, repo?: string): string | null { + const args = ["pr", "list", "--head", headBranch, "--json", "url", "--jq", ".[0].url // empty"]; + if (repo) args.push("--repo", repo); + const url = gh(args).trim(); + return url || null; +} + +export interface CreatePrOptions { + base: string; + head: string; + title: string; + bodyFile: string; + draft?: boolean; + repo?: string; +} + +export function createPr(opts: CreatePrOptions): string { + const args = ["pr", "create"]; + if (opts.draft) args.push("--draft"); + args.push("--base", opts.base, "--head", opts.head, "--title", opts.title, "--body-file", opts.bodyFile); + if (opts.repo) args.push("--repo", opts.repo); + return gh(args).trim(); +} + +// --- Issues --- + +export interface CreateIssueOptions { + title: string; + bodyFile: string; + repo?: string; +} + +export function createIssue(opts: CreateIssueOptions): string { + const args = ["issue", "create", "--title", opts.title, "--body-file", opts.bodyFile]; + if (opts.repo) args.push("--repo", opts.repo); + return gh(args).trim(); +} + +// --- Workflow dispatch --- + +function dispatchWorkflowPayload(repo: string, workflow: string, ref: string, inputs: Record): void { + const payload = JSON.stringify({ ref, inputs }); + execFileSync("gh", [ + "api", "-X", "POST", + `repos/${repo}/actions/workflows/${workflow}/dispatches`, + "--input", "-", + ], { + input: payload, + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: MAX_BUFFER, + }); +} + +function parseUnexpectedWorkflowInputs(err: unknown): string[] { + const match = commandErrorText(err).match(/Unexpected inputs provided:\s*(\[[^\]]*\])/i); + if (!match) return []; + try { + const parsed = JSON.parse(match[1]) as unknown; + return Array.isArray(parsed) + ? parsed.filter((value): value is string => typeof value === "string" && value.length > 0) + : []; + } catch { + return []; + } +} + +export function dispatchWorkflow( + repo: string, + workflow: string, + ref: string, + inputs: Record, +): void { + try { + dispatchWorkflowPayload(repo, workflow, ref, inputs); + return; + } catch (err: unknown) { + const unexpectedInputs = parseUnexpectedWorkflowInputs(err); + if (unexpectedInputs.length === 0) throw err; + + const retryInputs = { ...inputs }; + let removed = 0; + for (const name of unexpectedInputs) { + if (Object.prototype.hasOwnProperty.call(retryInputs, name)) { + delete retryInputs[name]; + removed += 1; + } + } + if (removed === 0) throw err; + + console.warn( + `Retrying ${workflow} dispatch without unsupported input(s): ${unexpectedInputs.join(", ")}`, + ); + dispatchWorkflowPayload(repo, workflow, ref, retryInputs); + } +} diff --git a/.agent/src/handoff.ts b/.agent/src/handoff.ts new file mode 100644 index 0000000..75c0873 --- /dev/null +++ b/.agent/src/handoff.ts @@ -0,0 +1,694 @@ +import { extractJsonObject } from "./response.js"; + +export type AgentAction = "implement" | "review" | "fix-pr" | "agent-self-approve" | "agent-self-merge"; +export type HandoffDecisionKind = "dispatch" | "delegate_issue" | "stop" | "skip"; +export type AutomationMode = "disabled" | "heuristics" | "agent"; +export type HandoffMarkerState = "pending" | "dispatched" | "failed"; +export type PlannerDecisionKind = "handoff" | "delegate_issue" | "answer" | "stop" | "blocked"; + +export interface HandoffInput { + automationMode: string; + sourceAction: string; + sourceConclusion: string; + sourceRecommendedNextStep?: string; + sourceHandoffContext?: string; + targetKind?: string; + targetNumber: string; + nextTargetNumber?: string; + currentRound: number; + maxRounds: number; + allowSelfApprove?: boolean; + allowSelfMerge?: boolean; + plannerDecision?: PlannerDecision | null; +} + +export interface HandoffDecision { + decision: HandoffDecisionKind; + nextAction?: AgentAction; + targetNumber?: string; + reason: string; + nextRound: number; + handoffContext?: string; + plannerDecisionKind?: PlannerDecisionKind; + userMessage?: string; + clarificationRequest?: string; + childStage?: string; + childInstructions?: string; + childIssueNumber?: string; + baseBranch?: string; + basePr?: string; +} + +export interface HandoffDedupeInput { + repo: string; + sourceRunId: string; + sourceAction: string; + sourceTargetNumber: string; + nextAction: string; + nextTargetNumber: string; + nextRound: number; +} + +export interface HandoffMarkerInfo { + state: HandoffMarkerState; + createdAtMs: number | null; +} + +export interface PlannerDecision { + decision: PlannerDecisionKind; + nextAction?: AgentAction; + reason: string; + handoffContext?: string; + userMessage?: string; + clarificationRequest?: string; + childStage?: string; + childInstructions?: string; + childIssueNumber?: string; + baseBranch?: string; + basePr?: string; +} + +const REVIEW_TO_FIX_PR = new Set(["minor_issues", "needs_rework", "changes_requested"]); +const SELF_APPROVAL_TO_FIX_PR = new Set(["request_changes", "changes_requested"]); +const PLANNER_DECISION_KINDS: Partial> = { + handoff: "handoff", + delegate_issue: "delegate_issue", + answer: "answer", + stop: "stop", + blocked: "blocked", +}; +const HANDOFF_MARKER_PREFIX = "sepo-agent-handoff"; +const DEFAULT_FIX_PR_HANDOFF_CONTEXT = [ + "Address only the latest unresolved review synthesis action items.", + "Ignore optional INFO notes, metadata-only polish, already-fixed findings, and human-judgment nits unless required by the selected fix.", +].join(" "); +const DEFAULT_SELF_APPROVAL_FIX_PR_HANDOFF_CONTEXT = [ + "Address only the self-approval REQUEST_CHANGES findings.", + "Preserve the reviewed-head and deterministic approval safeguards; avoid unrelated changes.", +].join(" "); +const ANY_HANDOFF_MARKER_RE = new RegExp( + ``, + "i", +); + +function normalizeToken(value: string): string { + return value.trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +function escapeRegex(text: string): string { + return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +export function normalizeAutomationMode(value: string): AutomationMode { + const normalized = normalizeToken(String(value || "")); + if (!normalized || normalized === "false") { + return "disabled"; + } + // Backward-compatible alias for early boolean-style automation config. + if (normalized === "true") { + return "heuristics"; + } + // The built-in heuristic state machine. Use the canonical plural spelling only. + if (normalized === "heuristics") { + return "heuristics"; + } + if (normalized === "agent") { + return "agent"; + } + return "disabled"; +} + +export function automationModeAllowsHandoff(value: string): boolean { + return normalizeAutomationMode(value) !== "disabled"; +} + +export function normalizeConclusion(value: string): string { + const normalized = normalizeToken(value); + if (normalized === "success") return "success"; + if (normalized === "ship") return "ship"; + if (normalized === "minor_issues") return "minor_issues"; + if (normalized === "needs_rework") return "needs_rework"; + if (normalized === "changes_requested") return "changes_requested"; + return normalized || "unknown"; +} + +export function normalizeRecommendedNextStep(value: string): string { + const normalized = normalizeToken(value); + if (normalized === "fix_pr") return "fix_pr"; + if (normalized === "human_decision") return "human_decision"; + if (normalized === "no_automated_action") return "no_automated_action"; + return normalized; +} + +export function formatMarkdownTableCell(value: string | number): string { + return String(value) + .replace(/\r?\n/g, " ") + .replace(/\|/g, "\\|") + .trim() || " "; +} + +export function formatTransposedMarkdownTable(headers: string[], values: Array): string[] { + return [ + `| ${headers.map(formatMarkdownTableCell).join(" | ")} |`, + `| ${headers.map(() => "---").join(" | ")} |`, + `| ${values.map(formatMarkdownTableCell).join(" | ")} |`, + ]; +} + +export function defaultFixPrHandoffContext(): string { + return DEFAULT_FIX_PR_HANDOFF_CONTEXT; +} + +function extractMarkdownSection(markdown: string, heading: string): string { + const lines = String(markdown || "").split(/\r?\n/); + const wanted = normalizeToken(heading); + const section: string[] = []; + let inSection = false; + for (const line of lines) { + const headingMatch = line.match(/^##\s+(.+?)\s*$/); + if (headingMatch) { + if (inSection) break; + inSection = normalizeToken(headingMatch[1]) === wanted; + continue; + } + if (inSection) section.push(line); + } + return section.join("\n").trim(); +} + +function normalizeReviewActionItem(line: string): string { + return line + .replace(/\s+/g, " ") + .trim(); +} + +export function extractReviewActionItems(markdown: string): string[] { + const section = extractMarkdownSection(markdown, "Action Items"); + if (!section) return []; + const items: string[] = []; + for (const line of section.split(/\r?\n/)) { + const checkbox = line.match(/^\s*[-*]\s+\[([ xX])\]\s+(.+?)\s*$/); + if (checkbox) { + if (checkbox[1].trim()) continue; + const item = normalizeReviewActionItem(checkbox[2]); + if (item) items.push(item); + continue; + } + const bullet = line.match(/^\s*[-*]\s+(.+?)\s*$/); + if (bullet) { + const item = normalizeReviewActionItem(bullet[1]); + if (item) items.push(item); + } + } + return items; +} + +export function buildReviewFixPrHandoffContext(markdown: string): string { + const items = extractReviewActionItems(markdown).slice(0, 5); + if (!items.length) return defaultFixPrHandoffContext(); + return [ + "Address only the latest review synthesis action items:", + ...items.map((item) => `- ${item}`), + "", + "Constraints: Ignore optional INFO notes, metadata-only polish, already-fixed findings, and human-judgment nits unless required by those action items.", + ].join("\n"); +} + +function resolveFixPrHandoffContext(input: HandoffInput): string { + return String(input.sourceHandoffContext || "").trim() || defaultFixPrHandoffContext(); +} + +function resolveSelfApprovalFixPrHandoffContext(input: HandoffInput): string { + return String(input.sourceHandoffContext || "").trim() || DEFAULT_SELF_APPROVAL_FIX_PR_HANDOFF_CONTEXT; +} + +function normalizeAgentAction(value: string): AgentAction | null { + const normalized = normalizeToken(value); + if (normalized === "implement") return "implement"; + if (normalized === "review") return "review"; + if (normalized === "fix_pr") return "fix-pr"; + if (normalized === "agent_self_approve") return "agent-self-approve"; + if (normalized === "agent_self_merge") return "agent-self-merge"; + return null; +} + +export function parsePlannerDecision(raw: string): PlannerDecision | null { + const json = extractJsonObject(raw); + if (!json) return null; + + let parsed: unknown; + try { + parsed = JSON.parse(json) as unknown; + } catch { + return null; + } + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null; + + const record = parsed as Record; + const decisionToken = normalizeToken(String(record.decision || "")); + const decision = PLANNER_DECISION_KINDS[decisionToken]; + if (!decision) return null; + + const nextAction = normalizeAgentAction(String(record.next_action ?? record.nextAction ?? "")); + const reason = String(record.reason || "").trim(); + const handoffContext = String(record.handoff_context ?? record.handoffContext ?? "").trim(); + const userMessage = String(record.user_message ?? record.userMessage ?? "").trim(); + const clarificationRequest = String( + record.clarification_request ?? record.clarificationRequest ?? "", + ).trim(); + const childStage = String(record.child_stage ?? record.childStage ?? record.stage ?? "").trim(); + const childInstructions = String( + record.child_instructions ?? record.childInstructions ?? record.task_instructions ?? record.taskInstructions ?? "", + ).trim(); + const childIssueNumber = String( + record.child_issue_number ?? record.childIssueNumber ?? record.target_issue_number ?? record.targetIssueNumber ?? "", + ).trim(); + const baseBranch = String(record.base_branch ?? record.baseBranch ?? "").trim(); + const basePr = String(record.base_pr ?? record.basePr ?? "").trim(); + const plannerDecision: PlannerDecision = { + decision, + nextAction: nextAction || undefined, + reason: reason || "agent planner returned no reason", + }; + if (handoffContext) { + plannerDecision.handoffContext = handoffContext; + } + if (userMessage) plannerDecision.userMessage = userMessage; + if (clarificationRequest) plannerDecision.clarificationRequest = clarificationRequest; + if (childStage) plannerDecision.childStage = childStage; + if (childInstructions) plannerDecision.childInstructions = childInstructions; + if (childIssueNumber) plannerDecision.childIssueNumber = childIssueNumber; + if (baseBranch) plannerDecision.baseBranch = baseBranch; + if (basePr) plannerDecision.basePr = basePr; + return plannerDecision; +} + +export function extractReviewConclusion(markdown: string): string { + const text = markdown || ""; + const verdictMatch = text.match(/##\s*Final Verdict\s*\n+\s*[-*]?\s*`?([A-Z_ -]+)`?/i); + if (verdictMatch) return normalizeConclusion(verdictMatch[1]); + + const inlineMatch = text.match(/\b(SHIP|MINOR[_ -]ISSUES|NEEDS[_ -]REWORK|CHANGES[_ -]REQUESTED)\b/i); + return inlineMatch ? normalizeConclusion(inlineMatch[1]) : "unknown"; +} + +export function extractReviewRecommendedNextStep(markdown: string): string { + const section = extractMarkdownSection(markdown, "Recommended Next Step"); + const text = section || markdown || ""; + const match = text.match(/\b(FIX_PR|HUMAN_DECISION|NO_AUTOMATED_ACTION)\b/i); + return match ? normalizeRecommendedNextStep(match[1]) : ""; +} + +export function buildHandoffDedupeKey(input: HandoffDedupeInput): string { + return [ + "handoff", + input.repo.trim().toLowerCase(), + input.sourceRunId.trim() || "unknown-run", + normalizeToken(input.sourceAction), + input.sourceTargetNumber.trim(), + normalizeToken(input.nextAction), + input.nextTargetNumber.trim(), + String(input.nextRound), + ].join(":"); +} + +function encodeMarkerKey(key: string): string { + return Buffer.from(key, "utf8").toString("base64url"); +} + +export function buildHandoffMarker( + key: string, + state: HandoffMarkerState = "dispatched", + createdAtMs = Date.now(), +): string { + return ``; +} + +export function parseHandoffMarker(body: string, key: string): HandoffMarkerInfo | null { + const encoded = escapeRegex(encodeMarkerKey(key)); + const markerRe = new RegExp( + ``, + "i", + ); + const match = String(body || "").match(markerRe); + if (!match) return null; + const rawState = String(match[1] || "dispatched").toLowerCase(); + const state: HandoffMarkerState = rawState === "pending" || rawState === "failed" + ? rawState + : "dispatched"; + const createdAtMs = match[2] ? Number.parseInt(match[2], 10) : NaN; + return { + state, + createdAtMs: Number.isFinite(createdAtMs) && createdAtMs > 0 ? createdAtMs : null, + }; +} + +export function getHandoffMarkerState(body: string, key: string): HandoffMarkerState | null { + return parseHandoffMarker(body, key)?.state ?? null; +} + +export function hasHandoffMarker(body: string, key: string): boolean { + return parseHandoffMarker(body, key) !== null; +} + +export function parseAnyHandoffMarker(body: string): HandoffMarkerInfo | null { + const match = String(body || "").match(ANY_HANDOFF_MARKER_RE); + if (!match) return null; + const rawState = String(match[1] || "dispatched").toLowerCase(); + const state: HandoffMarkerState = rawState === "pending" || rawState === "failed" + ? rawState + : "dispatched"; + const createdAtMs = match[2] ? Number.parseInt(match[2], 10) : NaN; + return { + state, + createdAtMs: Number.isFinite(createdAtMs) && createdAtMs > 0 ? createdAtMs : null, + }; +} + +export function hasAnyHandoffMarker(body: string): boolean { + return parseAnyHandoffMarker(body) !== null; +} + +export function isPendingHandoffMarkerStale( + marker: HandoffMarkerInfo, + nowMs: number, + ttlMs: number, +): boolean { + if (marker.state !== "pending") return false; + if (!marker.createdAtMs) return true; + return marker.createdAtMs + ttlMs <= nowMs; +} + +export function formatHandoffMarkerComment(args: { + key: string; + state?: HandoffMarkerState; + sourceAction: string; + nextAction: string; + targetKind?: string; + targetNumber?: string | number; + nextRound: number; + maxRounds: number; + reason: string; + handoffContext?: string; + error?: string; + createdAtMs?: number; +}): string { + const state = args.state || "dispatched"; + const status = state === "pending" + ? "pending" + : state === "failed" + ? "failed" + : "dispatched"; + const statusLabel = status.charAt(0).toUpperCase() + status.slice(1); + const normalizedTargetKind = normalizeToken(args.targetKind || ""); + const targetLabel = args.targetNumber + ? `${normalizedTargetKind === "issue" ? "Issue" : "PR"} #${args.targetNumber}` + : "Unknown"; + const lines = [ + status === "failed" + ? "Sepo could not dispatch follow-up automation." + : status === "pending" + ? "Sepo is preparing follow-up automation." + : "Sepo is dispatching follow-up automation.", + "", + ...formatTransposedMarkdownTable( + ["Source", "Next", "Target", "Round", "Status"], + [args.sourceAction, args.nextAction, targetLabel, `${args.nextRound} / ${args.maxRounds}`, statusLabel], + ), + "", + `Reason: ${args.reason}`, + ]; + + if (normalizeToken(args.nextAction) === "fix_pr") { + lines.push( + "", + "Task for fix-pr:", + String(args.handoffContext || "").trim() || defaultFixPrHandoffContext(), + ); + } + + if (args.error) { + lines.push("", `Dispatch error: ${args.error}`); + } + + lines.push("", buildHandoffMarker(args.key, state, args.createdAtMs)); + return lines.join("\n"); +} + +function decideHeuristicHandoff(input: HandoffInput): HandoffDecision { + const nextRound = input.currentRound + 1; + const sourceAction = normalizeToken(input.sourceAction); + const conclusion = normalizeConclusion(input.sourceConclusion); + const nextTarget = (input.nextTargetNumber || input.targetNumber).trim(); + + if (sourceAction === "implement") { + if (conclusion !== "success") { + return { decision: "stop", reason: `implement concluded ${conclusion}`, nextRound }; + } + if (!input.nextTargetNumber?.trim()) { + return { decision: "stop", reason: "implement did not produce a pull request target", nextRound }; + } + return { + decision: "dispatch", + nextAction: "review", + targetNumber: nextTarget, + reason: "implementation succeeded; dispatching review", + nextRound, + }; + } + + if (sourceAction === "fix_pr") { + if (conclusion !== "success") { + return { + decision: "stop", + reason: `fix-pr concluded ${conclusion}; no automatic handoff was dispatched because fix-pr must succeed before re-review`, + nextRound, + }; + } + return { + decision: "dispatch", + nextAction: "review", + targetNumber: nextTarget, + reason: "PR fixes succeeded; dispatching review", + nextRound, + }; + } + + if (sourceAction === "review") { + const recommendedNextStep = normalizeRecommendedNextStep(input.sourceRecommendedNextStep || ""); + if (recommendedNextStep === "human_decision") { + if (input.allowSelfApprove) { + return { + decision: "dispatch", + nextAction: "agent-self-approve", + targetNumber: nextTarget, + reason: `review recommended HUMAN_DECISION after ${conclusion}; dispatching agent-self-approve`, + nextRound, + }; + } + return { decision: "stop", reason: `review recommended HUMAN_DECISION after ${conclusion}`, nextRound }; + } + if (conclusion === "ship") { + if (input.allowSelfApprove) { + return { + decision: "dispatch", + nextAction: "agent-self-approve", + targetNumber: nextTarget, + reason: "review verdict is SHIP; dispatching agent-self-approve", + nextRound, + }; + } + return { decision: "stop", reason: "review verdict is SHIP", nextRound }; + } + if (REVIEW_TO_FIX_PR.has(conclusion)) { + return { + decision: "dispatch", + nextAction: "fix-pr", + targetNumber: nextTarget, + reason: `review verdict is ${conclusion}; dispatching fix-pr`, + nextRound, + handoffContext: resolveFixPrHandoffContext(input), + }; + } + return { decision: "stop", reason: `review verdict ${conclusion} has no handoff`, nextRound }; + } + + if (sourceAction === "agent_self_approve") { + if (SELF_APPROVAL_TO_FIX_PR.has(conclusion)) { + return { + decision: "dispatch", + nextAction: "fix-pr", + targetNumber: nextTarget, + reason: `agent-self-approve concluded ${conclusion}; dispatching fix-pr`, + nextRound, + handoffContext: resolveSelfApprovalFixPrHandoffContext(input), + }; + } + if (conclusion === "approved" && input.allowSelfMerge) { + return { + decision: "dispatch", + nextAction: "agent-self-merge", + targetNumber: nextTarget, + reason: "agent-self-approve concluded approved; dispatching agent-self-merge", + nextRound, + }; + } + return { decision: "stop", reason: `agent-self-approve concluded ${conclusion}`, nextRound }; + } + + if (sourceAction === "agent_self_merge") { + return { decision: "stop", reason: `agent-self-merge concluded ${conclusion}`, nextRound }; + } + + return { decision: "stop", reason: `unsupported source action ${input.sourceAction}`, nextRound }; +} + +function decideAgentHandoff(input: HandoffInput): HandoffDecision { + const nextRound = input.currentRound + 1; + const plannerDecision = input.plannerDecision; + if (!plannerDecision) { + return { decision: "stop", reason: "agent planner decision missing or invalid", nextRound }; + } + if (plannerDecision.decision === "stop" || plannerDecision.decision === "blocked") { + return { + decision: "stop", + reason: `agent planner ${plannerDecision.decision}: ${plannerDecision.reason}`, + nextRound, + plannerDecisionKind: plannerDecision.decision, + userMessage: plannerDecision.userMessage, + clarificationRequest: plannerDecision.clarificationRequest, + }; + } + if (plannerDecision.decision === "answer") { + if (plannerDecision.nextAction) { + return { decision: "stop", reason: "answer must not set next_action", nextRound }; + } + return { + decision: "stop", + reason: `agent planner answered: ${plannerDecision.reason}`, + nextRound, + plannerDecisionKind: "answer", + userMessage: plannerDecision.userMessage || plannerDecision.handoffContext, + }; + } + if (plannerDecision.decision === "delegate_issue") { + const sourceAction = normalizeToken(input.sourceAction); + const targetKind = normalizeToken(input.targetKind || ""); + if (plannerDecision.nextAction) { + return { decision: "stop", reason: "delegate_issue must not set next_action", nextRound }; + } + if (sourceAction !== "orchestrate") { + return { decision: "stop", reason: "delegate_issue is only allowed from meta orchestration", nextRound }; + } + if (targetKind && targetKind !== "issue") { + return { decision: "stop", reason: "meta orchestration can delegate child issues only from issues", nextRound }; + } + if (plannerDecision.baseBranch && plannerDecision.basePr) { + return { decision: "stop", reason: "agent planner set both base_branch and base_pr", nextRound }; + } + if (!plannerDecision.childIssueNumber && !plannerDecision.childInstructions && !plannerDecision.handoffContext) { + return { + decision: "stop", + reason: "agent planner requested child issue delegation without child instructions or existing issue", + nextRound, + }; + } + return { + decision: "delegate_issue", + reason: `agent planner selected child issue delegation: ${plannerDecision.reason}`, + nextRound, + targetNumber: plannerDecision.childIssueNumber || input.targetNumber, + handoffContext: plannerDecision.handoffContext, + childStage: plannerDecision.childStage || `stage-${nextRound - 1}`, + childInstructions: plannerDecision.childInstructions || plannerDecision.handoffContext, + childIssueNumber: plannerDecision.childIssueNumber, + baseBranch: plannerDecision.baseBranch, + basePr: plannerDecision.basePr, + }; + } + if (!plannerDecision.nextAction) { + return { decision: "stop", reason: "agent planner requested handoff without next_action", nextRound }; + } + + const sourceAction = normalizeToken(input.sourceAction); + const targetKind = normalizeToken(input.targetKind || ""); + if (sourceAction === "orchestrate" && plannerDecision.nextAction === "implement") { + if (targetKind && targetKind !== "issue") { + return { decision: "stop", reason: "issue orchestration can dispatch implement only for issue targets", nextRound }; + } + if (plannerDecision.baseBranch && plannerDecision.basePr) { + return { decision: "stop", reason: "agent planner set both base_branch and base_pr", nextRound }; + } + return { + decision: "dispatch", + nextAction: "implement", + targetNumber: input.targetNumber, + reason: `agent planner selected implement: ${plannerDecision.reason}`, + nextRound, + handoffContext: plannerDecision.handoffContext, + baseBranch: plannerDecision.baseBranch, + basePr: plannerDecision.basePr, + }; + } + if (sourceAction === "orchestrate" && targetKind === "pull_request") { + if (plannerDecision.nextAction === "review" || plannerDecision.nextAction === "fix-pr") { + if (plannerDecision.nextAction === "fix-pr" && !plannerDecision.handoffContext) { + return { + decision: "stop", + reason: "agent planner selected fix-pr for PR orchestration without handoff_context", + nextRound, + }; + } + return { + decision: "dispatch", + nextAction: plannerDecision.nextAction, + targetNumber: input.targetNumber, + reason: `agent planner selected ${plannerDecision.nextAction}: ${plannerDecision.reason}`, + nextRound, + handoffContext: plannerDecision.handoffContext, + }; + } + return { + decision: "stop", + reason: `agent planner requested ${plannerDecision.nextAction}, but PR orchestration can dispatch only review or fix-pr`, + nextRound, + }; + } + + const allowed = decideHeuristicHandoff(input); + if (allowed.decision !== "dispatch" || !allowed.nextAction) { + return { + decision: "stop", + reason: `agent planner requested ${plannerDecision.nextAction}, but policy disallows handoff: ${allowed.reason}`, + nextRound, + }; + } + if (plannerDecision.nextAction !== allowed.nextAction) { + return { + decision: "stop", + reason: `agent planner requested ${plannerDecision.nextAction}, but policy only allows ${allowed.nextAction}`, + nextRound, + }; + } + + return { + ...allowed, + reason: `agent planner selected ${allowed.nextAction}: ${plannerDecision.reason}`, + handoffContext: plannerDecision.handoffContext || allowed.handoffContext, + }; +} + +export function decideHandoff(input: HandoffInput): HandoffDecision { + const nextRound = input.currentRound + 1; + const automationMode = normalizeAutomationMode(input.automationMode); + if (automationMode === "disabled") { + return { decision: "skip", reason: "automation mode is disabled", nextRound }; + } + if (input.currentRound >= input.maxRounds) { + return { decision: "stop", reason: "automation round budget exhausted", nextRound }; + } + if (automationMode === "agent") { + return decideAgentHandoff(input); + } + return decideHeuristicHandoff(input); +} diff --git a/.agent/src/implementation-base.ts b/.agent/src/implementation-base.ts new file mode 100644 index 0000000..aa9010b --- /dev/null +++ b/.agent/src/implementation-base.ts @@ -0,0 +1,107 @@ +import { appendFileSync } from "node:fs"; +import { randomBytes } from "node:crypto"; +import { fetchPrMeta } from "./github.js"; +import { setOutput } from "./output.js"; + +export interface ResolveImplementationBaseOptions { + baseBranch?: string; + basePr?: string; + defaultBranch: string; + repo?: string; +} + +export interface ResolvedImplementationBase { + baseBranch: string; + source: "default_branch" | "base_branch" | "base_pr"; + basePr?: number; +} + +function normalizeInput(value: string | undefined): string { + return String(value || "").trim(); +} + +export function validateBaseBranch(value: string): string { + const branch = normalizeInput(value); + if (!branch) { + throw new Error("base branch is required"); + } + if (branch.startsWith("-")) { + throw new Error("base branch must not start with '-'"); + } + if ( + branch.startsWith("/") || + branch.endsWith("/") || + branch.includes("..") || + branch.includes("//") || + branch.endsWith(".") || + branch === "@" || + branch.includes("@{") || + /(^|\/)\./.test(branch) || + /(^|\/)[^/]+\.lock(\/|$)/.test(branch) || + /[\s~^:?*[\]\\\x00-\x1f\x7f]/.test(branch) + ) { + throw new Error(`invalid base branch: ${branch}`); + } + return branch; +} + +function parseBasePr(value: string): number { + if (!/^[1-9][0-9]*$/.test(value)) { + throw new Error("base_pr must be a positive integer"); + } + return Number.parseInt(value, 10); +} + +export function resolveImplementationBase( + opts: ResolveImplementationBaseOptions, +): ResolvedImplementationBase { + const explicitBranch = normalizeInput(opts.baseBranch); + const explicitPr = normalizeInput(opts.basePr); + const defaultBranch = validateBaseBranch(opts.defaultBranch); + + if (explicitBranch && explicitPr) { + throw new Error("set only one of base_branch or base_pr"); + } + + if (explicitBranch) { + return { + baseBranch: validateBaseBranch(explicitBranch), + source: "base_branch", + }; + } + + if (explicitPr) { + const basePr = parseBasePr(explicitPr); + const meta = fetchPrMeta(basePr, opts.repo); + if (meta.isCrossRepository) { + throw new Error(`base_pr #${basePr} is from a fork; only same-repository PR heads are supported`); + } + if (meta.state.toUpperCase() !== "OPEN") { + throw new Error(`base_pr #${basePr} must be open`); + } + return { + baseBranch: validateBaseBranch(meta.headRef), + source: "base_pr", + basePr, + }; + } + + return { + baseBranch: defaultBranch, + source: "default_branch", + }; +} + +function appendGithubEnv(name: string, value: string): void { + const envFile = process.env.GITHUB_ENV; + if (!envFile) return; + const delim = `DELIM_${randomBytes(8).toString("hex")}`; + appendFileSync(envFile, `${name}<<${delim}\n${value}\n${delim}\n`); +} + +export function exportImplementationBase(result: ResolvedImplementationBase): void { + appendGithubEnv("BASE_BRANCH", result.baseBranch); + setOutput("base_branch", result.baseBranch); + setOutput("source", result.source); + setOutput("base_pr", result.basePr ? String(result.basePr) : ""); +} diff --git a/.agent/src/memory-artifacts.ts b/.agent/src/memory-artifacts.ts new file mode 100644 index 0000000..0d458e9 --- /dev/null +++ b/.agent/src/memory-artifacts.ts @@ -0,0 +1,118 @@ +// Memory branch layout helpers. +// +// The agent writes prose into PROJECT.md / MEMORY.md / daily/ through the +// memory-update CLI. The deterministic sync mirror under github/// +// is dumped as raw `gh --json` output — one JSON file per item, type encoded +// in the filename. No custom markdown rendering. + +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +export const GITHUB_DIR = "github"; +export const DAILY_DIR = "daily"; + +export const MEMORY_README = [ + "# Agent memory", + "", + "This branch stores durable context for Sepo agents. It is separate from `main` so memory updates do not mix with product code.", + "", + "## Layout", + "", + "- `PROJECT.md` holds slow-changing project context: goals, constraints, and open questions.", + "- `MEMORY.md` holds durable conventions and lessons the agent should carry forward.", + "- `daily/YYYY-MM-DD.md` holds append-only daily activity bullets.", + "- `github///*.json` mirrors repository issues, pull requests, and discussions for lookup.", + "- Mirrored artifacts can be cited in notes as backlink-style paths, for example `[[github///issue-1.json]]`.", + "", + "These files are the starting structure. Agents may add other notes when that keeps durable context easier to use.", + "", + "## Tools", + "", + "Memory-related CLI tools live on the `main` branch under `.agent/dist/cli/memory/` after the agent package is built. Useful tools include:", + "", + "- `search.js` for searching markdown and JSON memory files.", + "- `update.js` for adding, replacing, removing, or appending standard memory bullets.", + "", +].join("\n"); + +export interface EnsureMemoryStructureResult { + createdFiles: string[]; +} + +function ensureDirectory(path: string): void { + mkdirSync(path, { recursive: true }); +} + +function ensureFile(path: string, content: string, createdFiles: string[]): void { + if (existsSync(path)) return; + ensureDirectory(dirname(path)); + writeFileSync(path, content, "utf8"); + createdFiles.push(path); +} + +function splitRepoSlug(repoSlug: string): [string, string] { + const parts = repoSlug.split("/"); + if ( + parts.length !== 2 + || !parts[0] + || !parts[1] + || parts.some((part) => part === "." || part === ".." || part.includes("\\")) + ) { + throw new Error(`Invalid repository slug: ${repoSlug || "empty"}`); + } + return [parts[0], parts[1]]; +} + +/** + * Creates the memory branch layout and seeds README.md, PROJECT.md, and + * MEMORY.md if missing. Idempotent. + */ +export function ensureMemoryStructure(rootDir: string, repoSlug: string): EnsureMemoryStructureResult { + const createdFiles: string[] = []; + splitRepoSlug(repoSlug); + + ensureDirectory(join(rootDir, DAILY_DIR)); + ensureDirectory(join(rootDir, GITHUB_DIR)); + ensureDirectory(githubArtifactDir(rootDir, repoSlug)); + ensureFile(join(rootDir, DAILY_DIR, ".gitkeep"), "", createdFiles); + ensureFile(join(rootDir, GITHUB_DIR, ".gitkeep"), "", createdFiles); + ensureFile(join(githubArtifactDir(rootDir, repoSlug), ".gitkeep"), "", createdFiles); + + ensureFile(join(rootDir, "PROJECT.md"), "", createdFiles); + ensureFile(join(rootDir, "MEMORY.md"), "", createdFiles); + ensureFile(join(rootDir, "README.md"), MEMORY_README, createdFiles); + + return { createdFiles }; +} + +// Repo-aware layout: each repository gets its own namespace under github/. +// Type is encoded in the filename, so issue #209, PR #209, and discussion #209 +// never collide inside the same repo namespace. + +export function githubArtifactDir(rootDir: string, repoSlug: string): string { + const [owner, repo] = splitRepoSlug(repoSlug); + return join(rootDir, GITHUB_DIR, owner, repo); +} + +export function issueArtifactPath(rootDir: string, repoSlug: string, number: number): string { + return join(githubArtifactDir(rootDir, repoSlug), `issue-${number}.json`); +} + +export function pullRequestArtifactPath(rootDir: string, repoSlug: string, number: number): string { + return join(githubArtifactDir(rootDir, repoSlug), `pull-${number}.json`); +} + +export function discussionArtifactPath(rootDir: string, repoSlug: string, number: number): string { + return join(githubArtifactDir(rootDir, repoSlug), `discussion-${number}.json`); +} + +/** + * Writes `content` to `path` iff it would change the file. Returns whether + * an on-disk write happened. + */ +export function writeFileIfChanged(path: string, content: string): boolean { + ensureDirectory(dirname(path)); + if (existsSync(path) && readFileSync(path, "utf8") === content) return false; + writeFileSync(path, content, "utf8"); + return true; +} diff --git a/.agent/src/memory-policy.ts b/.agent/src/memory-policy.ts new file mode 100644 index 0000000..6d6dc32 --- /dev/null +++ b/.agent/src/memory-policy.ts @@ -0,0 +1,104 @@ +// Parses AGENT_MEMORY_POLICY, the repository-level configuration for which +// routes can read / write agent memory. +// +// Shape (both sections optional): +// { +// "default_mode": "enabled" | "read-only" | "disabled", +// "route_overrides": { +// "": "enabled" | "read-only" | "disabled", +// ... +// } +// } +// +// Default when the variable is empty or unset: every route gets "enabled". +// Modes: +// - enabled — download memory before the run; commit+push edits after +// - read-only — download memory before the run; skip the commit step +// - disabled — skip memory entirely + +export const MEMORY_MODES = ["enabled", "read-only", "disabled"] as const; +export type MemoryMode = typeof MEMORY_MODES[number]; +export const DEFAULT_MEMORY_MODE: MemoryMode = "enabled"; + +const VALID_MODE_SET: ReadonlySet = new Set(MEMORY_MODES); +const VALID_ROUTE_KEY = /^[a-z0-9][a-z0-9._-]*$/; + +export interface MemoryPolicy { + defaultMode: MemoryMode; + routeOverrides: Record; +} + +function normalizeMode(value: unknown, label: string): MemoryMode { + const normalized = String(value || "").trim().toLowerCase(); + if (!VALID_MODE_SET.has(normalized)) { + throw new Error( + `${label} must be one of ${MEMORY_MODES.join(", ")} (got ${normalized || "empty"})`, + ); + } + return normalized as MemoryMode; +} + +export function parseMemoryPolicy(raw: string): MemoryPolicy { + const text = String(raw || "").trim(); + if (!text) { + return { defaultMode: DEFAULT_MEMORY_MODE, routeOverrides: {} }; + } + + const payload = JSON.parse(text) as Record; + if (!payload || typeof payload !== "object" || Array.isArray(payload)) { + throw new Error("Memory policy must be a JSON object"); + } + + const policy: MemoryPolicy = { + defaultMode: DEFAULT_MEMORY_MODE, + routeOverrides: {}, + }; + + if ("default_mode" in payload) { + policy.defaultMode = normalizeMode(payload.default_mode, "default_mode"); + } + + if ("route_overrides" in payload) { + const overrides = payload.route_overrides; + if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) { + throw new Error("route_overrides must be an object"); + } + for (const [route, mode] of Object.entries(overrides)) { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (!VALID_ROUTE_KEY.test(normalizedRoute)) { + throw new Error( + `Invalid route override key in memory policy: ${normalizedRoute || "missing"}`, + ); + } + policy.routeOverrides[normalizedRoute] = normalizeMode( + mode, + `route_overrides.${normalizedRoute}`, + ); + } + } + + return policy; +} + +export function getMemoryModeForRoute( + policy: MemoryPolicy, + route: string, +): MemoryMode { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (normalizedRoute && normalizedRoute in policy.routeOverrides) { + return policy.routeOverrides[normalizedRoute]!; + } + return policy.defaultMode; +} + +export function memoryModeAllowsRead(mode: MemoryMode): boolean { + return mode !== "disabled"; +} + +export function memoryModeAllowsWrite(mode: MemoryMode): boolean { + return mode === "enabled"; +} + +export function isMemoryMode(value: unknown): value is MemoryMode { + return typeof value === "string" && VALID_MODE_SET.has(value); +} diff --git a/.agent/src/memory-search.ts b/.agent/src/memory-search.ts new file mode 100644 index 0000000..97d8554 --- /dev/null +++ b/.agent/src/memory-search.ts @@ -0,0 +1,295 @@ +// Filesystem text search over a memory directory tree. +// +// Intentionally simple: no pre-built index, no stemming. The memory tree is +// small enough (MB range) that walking it per query is fine, and we avoid a +// stale-index class of bugs. The agent invokes this on demand through the +// cli/memory/search.js CLI. + +import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; +import { basename, extname, join, relative, resolve, sep } from "node:path"; + +export interface MemorySearchLineMatch { + lineNumber: number; + text: string; + score: number; + matchCount: number; +} + +export interface MemorySearchResult { + path: string; + absolutePath: string; + score: number; + matchCount: number; + matchedTerms: string[]; + snippets: MemorySearchLineMatch[]; +} + +export interface MemorySearchOptions { + rootDir: string; + limit?: number; + snippetsPerFile?: number; + maxFileSizeBytes?: number; +} + +const DEFAULT_LIMIT = 5; +const DEFAULT_SNIPPETS_PER_FILE = 3; +const DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024; +const PATH_MATCH_WEIGHT = 6; +const PHRASE_MATCH_WEIGHT = 3; + +const SKIPPED_DIRECTORIES = new Set([ + ".git", + ".hg", + ".svn", + "node_modules", +]); + +const TEXT_FILE_EXTENSIONS = new Set([ + ".md", + ".markdown", + ".txt", + ".json", + ".jsonl", + ".yaml", + ".yml", + ".csv", + ".tsv", + ".log", +]); + +function toPosixPath(value: string): string { + return value.split(sep).join("/"); +} + +function countOccurrences(haystack: string, needle: string): number { + if (!haystack || !needle) return 0; + let count = 0; + let fromIndex = 0; + while (fromIndex < haystack.length) { + const index = haystack.indexOf(needle, fromIndex); + if (index === -1) break; + count += 1; + fromIndex = index + Math.max(needle.length, 1); + } + return count; +} + +function normalizeSearchPhrase(query: string): string { + return String(query || "").trim().toLowerCase(); +} + +export function tokenizeMemorySearchQuery(query: string): string[] { + const normalized = String(query || "").trim().toLowerCase(); + if (!normalized) return []; + + const seen = new Set(); + const tokens = normalized + .split(/[^a-z0-9]+/i) + .map((token) => token.trim()) + .filter((token) => token.length >= 2 || /^[0-9]+$/.test(token)) + .filter((token) => { + if (seen.has(token)) return false; + seen.add(token); + return true; + }); + + if (tokens.length > 0) return tokens; + return normalized.length >= 2 ? [normalized] : []; +} + +function collectSearchableFiles(rootDir: string): string[] { + const files: string[] = []; + const stack = [rootDir]; + + while (stack.length > 0) { + const current = stack.pop()!; + let entries; + try { + entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => + a.name.localeCompare(b.name), + ); + } catch { + continue; + } + + for (const entry of entries) { + const fullPath = join(current, entry.name); + if (entry.isDirectory()) { + if (SKIPPED_DIRECTORIES.has(entry.name)) continue; + stack.push(fullPath); + continue; + } + if (entry.isFile()) files.push(fullPath); + } + } + + return files.sort(); +} + +function readTextFile(filePath: string, maxFileSizeBytes: number): string | null { + const stat = statSync(filePath); + if (!stat.isFile() || stat.size > maxFileSizeBytes) return null; + + const extension = extname(filePath).toLowerCase(); + const buffer = readFileSync(filePath); + if (!TEXT_FILE_EXTENSIONS.has(extension) && buffer.includes(0)) return null; + + return buffer.toString("utf8"); +} + +function summarizeLine(text: string, maxLength = 220): string { + const collapsed = text.replace(/\s+/g, " ").trim(); + if (collapsed.length <= maxLength) return collapsed; + return collapsed.slice(0, maxLength).trimEnd() + "…"; +} + +function scoreLine(line: string, tokens: string[]): { score: number; count: number; terms: string[] } { + const lower = line.toLowerCase(); + let score = 0; + let count = 0; + const terms: string[] = []; + for (const token of tokens) { + const occurrences = countOccurrences(lower, token); + if (occurrences > 0) { + score += occurrences * Math.max(token.length, 2); + count += occurrences; + terms.push(token); + } + } + return { score, count, terms }; +} + +function scorePath(pathValue: string, tokens: string[]): { score: number; count: number; terms: string[] } { + const lower = pathValue.toLowerCase(); + let score = 0; + let count = 0; + const terms: string[] = []; + for (const token of tokens) { + const occurrences = countOccurrences(lower, token); + if (occurrences > 0) { + score += occurrences * Math.max(token.length, 2) * PATH_MATCH_WEIGHT; + count += occurrences; + terms.push(token); + } + } + return { score, count, terms }; +} + +export function searchMemory( + query: string, + options: MemorySearchOptions, +): MemorySearchResult[] { + const tokens = tokenizeMemorySearchQuery(query); + if (tokens.length === 0) return []; + + const root = resolve(options.rootDir); + if (!existsSync(root)) { + throw new Error(`Memory directory not found: ${root}`); + } + if (!statSync(root).isDirectory()) { + throw new Error(`Memory path is not a directory: ${root}`); + } + + const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT); + const snippetsPerFile = Math.max(1, options.snippetsPerFile ?? DEFAULT_SNIPPETS_PER_FILE); + const maxFileSizeBytes = options.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES; + const phrase = normalizeSearchPhrase(query); + + const files = collectSearchableFiles(root); + const results: MemorySearchResult[] = []; + + for (const filePath of files) { + let content: string | null; + try { + content = readTextFile(filePath, maxFileSizeBytes); + } catch { + continue; + } + if (!content) continue; + + const lines = content.split(/\r?\n/); + const lineMatches: MemorySearchLineMatch[] = []; + const relativePath = toPosixPath(relative(root, filePath)) || basename(filePath); + const pathScored = scorePath(relativePath, tokens); + let fileScore = pathScored.score; + let fileMatches = pathScored.count; + const termsSeen = new Set(); + for (const term of pathScored.terms) termsSeen.add(term); + + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index]!; + if (!line.trim()) continue; + const scored = scoreLine(line, tokens); + const phraseCount = phrase.length >= 2 ? countOccurrences(line.toLowerCase(), phrase) : 0; + if (phraseCount > 0) { + scored.score += phraseCount * Math.max(phrase.length, 4) * PHRASE_MATCH_WEIGHT; + scored.count += phraseCount; + } + if (scored.count === 0) continue; + fileScore += scored.score; + fileMatches += scored.count; + for (const term of scored.terms) termsSeen.add(term); + lineMatches.push({ + lineNumber: index + 1, + text: summarizeLine(line), + score: scored.score, + matchCount: scored.count, + }); + } + + if (lineMatches.length === 0) { + if (pathScored.score === 0) continue; + lineMatches.push({ + lineNumber: 0, + text: "(matched by filename)", + score: pathScored.score, + matchCount: pathScored.count, + }); + } + + // Prefer lines matching more distinct terms first, then higher score. + lineMatches.sort((a, b) => b.score - a.score || a.lineNumber - b.lineNumber); + + results.push({ + path: relativePath, + absolutePath: filePath, + score: fileScore, + matchCount: fileMatches, + matchedTerms: Array.from(termsSeen), + snippets: lineMatches.slice(0, snippetsPerFile), + }); + } + + results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)); + return results.slice(0, limit); +} + +export function formatMemorySearchResults( + query: string, + results: MemorySearchResult[], + rootDir: string, +): string { + const header = `Memory search: "${query}" (${results.length} file${results.length === 1 ? "" : "s"} in ${resolve(rootDir)})\n`; + if (results.length === 0) { + return `${header}\n_No matches found._\n`; + } + + const body = results + .map((result) => { + const lines = [ + `\n## ${result.path} (score=${result.score}, matches=${result.matchCount})`, + `Matched terms: ${result.matchedTerms.join(", ") || "(none)"}`, + ]; + for (const snippet of result.snippets) { + lines.push( + snippet.lineNumber > 0 + ? ` L${snippet.lineNumber}: ${snippet.text}` + : ` Path match: ${snippet.text}`, + ); + } + return lines.join("\n"); + }) + .join("\n"); + + return `${header}${body}\n`; +} diff --git a/.agent/src/memory-sync-state.ts b/.agent/src/memory-sync-state.ts new file mode 100644 index 0000000..7e19699 --- /dev/null +++ b/.agent/src/memory-sync-state.ts @@ -0,0 +1,201 @@ +// Ref-backed sync cursors for the memory branch. +// +// Stored at refs/agent-memory-state/sync as a one-file tree. Separate from the +// agent/memory branch so cursor updates don't pollute the memory content +// history and don't race with memory commits. + +import { buildAuthUrl, git } from "./git.js"; + +export const MEMORY_SYNC_STATE_SCHEMA_VERSION = 1; +export const MEMORY_SYNC_STATE_REF = "refs/agent-memory-state/sync"; +const STATE_FILENAME = "state.json"; +const REF_NOT_FOUND_PATTERN = /couldn't find remote ref|no matching remote head/i; + +export interface MemorySyncCursors { + issues: string; + pulls: string; + discussions: string; + commits: string; +} + +export interface MemorySyncState { + schema_version: number; + repo_slug: string; + last_sync_at: string; + last_activity_at: string; + cursors: MemorySyncCursors; + last_run_url: string; + created_at: string; + updated_at: string; +} + +interface MemorySyncStateRecord extends Record { + schema_version?: unknown; + repo_slug?: unknown; + last_sync_at?: unknown; + last_activity_at?: unknown; + cursors?: unknown; + last_run_url?: unknown; + created_at?: unknown; + updated_at?: unknown; +} + +export interface MemorySyncStateUpdates { + last_sync_at?: string; + last_activity_at?: string; + cursors?: Partial; + last_run_url?: string; +} + +export interface PushOptions { + remote?: string; + token?: string; + repo?: string; +} + +function toStringOrEmpty(value: unknown): string { + return typeof value === "string" ? value : ""; +} + +function toIsoOrNow(value: unknown, fallback: string): string { + return typeof value === "string" && value ? value : fallback; +} + +function normalizeCursors(raw: unknown): MemorySyncCursors { + const record = raw && typeof raw === "object" ? (raw as Record) : {}; + return { + issues: toStringOrEmpty(record.issues), + pulls: toStringOrEmpty(record.pulls), + discussions: toStringOrEmpty(record.discussions), + commits: toStringOrEmpty(record.commits), + }; +} + +function resolveRemoteTarget(remote: string, opts?: PushOptions): string { + if (opts?.token && opts?.repo) return buildAuthUrl(opts.token, opts.repo); + return remote; +} + +export function createMemorySyncState(repoSlug: string): MemorySyncState { + const now = new Date().toISOString(); + return { + schema_version: MEMORY_SYNC_STATE_SCHEMA_VERSION, + repo_slug: repoSlug, + last_sync_at: "", + last_activity_at: "", + cursors: { issues: "", pulls: "", discussions: "", commits: "" }, + last_run_url: "", + created_at: now, + updated_at: now, + }; +} + +export function updateMemorySyncState( + state: MemorySyncState, + updates: MemorySyncStateUpdates, +): MemorySyncState { + return { + ...state, + last_sync_at: updates.last_sync_at ?? state.last_sync_at, + last_activity_at: updates.last_activity_at ?? state.last_activity_at, + cursors: { ...state.cursors, ...(updates.cursors || {}) }, + last_run_url: updates.last_run_url ?? state.last_run_url, + schema_version: state.schema_version, + repo_slug: state.repo_slug, + created_at: state.created_at, + updated_at: new Date().toISOString(), + }; +} + +export function normalizeMemorySyncState(raw: unknown): MemorySyncState | null { + if (!raw || typeof raw !== "object") return null; + + const record = raw as MemorySyncStateRecord; + const repoSlug = toStringOrEmpty(record.repo_slug); + if (!repoSlug) return null; + + const now = new Date().toISOString(); + return { + schema_version: MEMORY_SYNC_STATE_SCHEMA_VERSION, + repo_slug: repoSlug, + last_sync_at: toStringOrEmpty(record.last_sync_at), + last_activity_at: toStringOrEmpty(record.last_activity_at), + cursors: normalizeCursors(record.cursors), + last_run_url: toStringOrEmpty(record.last_run_url), + created_at: toIsoOrNow(record.created_at, now), + updated_at: toIsoOrNow(record.updated_at, now), + }; +} + +export function memorySyncStateForRepo( + state: MemorySyncState | null, + repoSlug: string, +): MemorySyncState | null { + if (!state) return null; + return state.repo_slug === repoSlug ? state : null; +} + +export function fetchMemorySyncState( + cwd: string, + opts?: PushOptions, +): MemorySyncState | null { + const origin = opts?.remote ?? "origin"; + const fetchTarget = resolveRemoteTarget(origin, opts); + + try { + git(["fetch", "--no-tags", fetchTarget, `+${MEMORY_SYNC_STATE_REF}:${MEMORY_SYNC_STATE_REF}`], cwd); + } catch (err: unknown) { + const stderr = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + if (REF_NOT_FOUND_PATTERN.test(stderr)) return null; + throw err; + } + + try { + const json = git(["cat-file", "blob", `${MEMORY_SYNC_STATE_REF}:${STATE_FILENAME}`], cwd); + return normalizeMemorySyncState(JSON.parse(json)); + } catch { + return null; + } +} + +export function writeMemorySyncState( + state: MemorySyncState, + cwd: string, + opts?: PushOptions, +): void { + const origin = opts?.remote ?? "origin"; + const json = JSON.stringify(state, null, 2) + "\n"; + + const blobSha = git(["hash-object", "-w", "--stdin"], cwd, json); + const treeInput = `100644 blob ${blobSha}\t${STATE_FILENAME}\n`; + const treeSha = git(["mktree"], cwd, treeInput); + + let parentArg: string[]; + let expectedOid: string | null = null; + try { + const parentSha = git(["rev-parse", "--verify", MEMORY_SYNC_STATE_REF], cwd); + parentArg = ["-p", parentSha]; + expectedOid = parentSha; + } catch { + parentArg = []; + } + + const commitSha = git( + [ + "commit-tree", + treeSha, + ...parentArg, + "-m", + `memory-sync-state: ${state.last_sync_at || "unsynced"}`, + ], + cwd, + ); + + git(["update-ref", MEMORY_SYNC_STATE_REF, commitSha], cwd); + + const pushTarget = resolveRemoteTarget(origin, opts); + const leaseArg = expectedOid + ? `--force-with-lease=${MEMORY_SYNC_STATE_REF}:${expectedOid}` + : "--force"; + git(["push", leaseArg, pushTarget, `${MEMORY_SYNC_STATE_REF}:${MEMORY_SYNC_STATE_REF}`], cwd); +} diff --git a/.agent/src/memory-update.ts b/.agent/src/memory-update.ts new file mode 100644 index 0000000..124cf61 --- /dev/null +++ b/.agent/src/memory-update.ts @@ -0,0 +1,395 @@ +// Safe, validated bullet-level edits to MEMORY.md / PROJECT.md / daily logs. +// +// The main agent composes memory during normal execution routes; this module +// is the sanctioned helper for validated bullet-level edits when the agent +// wants section placement, formatting, and dedup handled automatically. + +import { + closeSync, + existsSync, + mkdirSync, + openSync, + readFileSync, + renameSync, + rmSync, + statSync, + writeFileSync, +} from "node:fs"; +import { basename, dirname, join } from "node:path"; + +export const MEMORY_FILE = "MEMORY.md"; +export const PROJECT_FILE = "PROJECT.md"; +export const DAILY_DIR = "daily"; +export const DAILY_ACTIVITY_SECTION = "Activity"; + +export type EditableFile = typeof MEMORY_FILE | typeof PROJECT_FILE; + +// Outcomes of a mutation attempt. `deduped` means: `replace` resolved a match, +// but the `--with` replacement already exists as a distinct bullet in the +// section, so the matched source bullet is removed and the existing target is +// left in place (net effect: one fewer bullet, no duplicate created). +export type UpdateAction = + | { kind: "added" } + | { kind: "deduped" } + | { kind: "noop"; reason: "duplicate" } + | { kind: "replaced" } + | { kind: "removed" } + | { kind: "missing_section"; section: string } + | { kind: "missing_match"; match: string } + | { kind: "ambiguous_match"; match: string; candidates: string[] }; + +export interface UpdateResult { + action: UpdateAction; + file: string; +} + +const LOCK_TIMEOUT_MS = 5_000; +const LOCK_POLL_MS = 50; +const STALE_LOCK_MS = 30_000; +const PREVIEW_CHARS = 120; + +const LOCK_SLEEP_ARRAY = new Int32Array(new SharedArrayBuffer(4)); + +function normalizeBullet(raw: string): string { + const collapsed = String(raw || "") + .replace(/\r/g, "") + .replace(/\s+/g, " ") + .trim(); + if (!collapsed) return ""; + const stripped = collapsed.replace(/^[-*+]\s+/, ""); + if (!stripped) return ""; + return `- ${stripped}`; +} + +function sectionHeader(name: string): string { + return `## ${name}`; +} + +function titleForEditableFile(file: EditableFile): string { + return file === MEMORY_FILE ? "Memory" : "Project"; +} + +function seedEmptyEditableFile(file: EditableFile, section: string): string[] { + return [`# ${titleForEditableFile(file)}`, "", sectionHeader(section)]; +} + +interface SectionSpan { + headerIndex: number; + bodyStart: number; + bodyEnd: number; +} + +function findSection(lines: string[], name: string): SectionSpan | null { + const header = sectionHeader(name).trim(); + const headerIndex = lines.findIndex((line) => line.trim() === header); + if (headerIndex === -1) return null; + + let bodyEnd = lines.length; + for (let i = headerIndex + 1; i < lines.length; i += 1) { + if (/^##\s+/.test(lines[i]!)) { + bodyEnd = i; + break; + } + } + return { headerIndex, bodyStart: headerIndex + 1, bodyEnd }; +} + +function bulletsInSpan(lines: string[], span: SectionSpan): string[] { + return lines + .slice(span.bodyStart, span.bodyEnd) + .filter((line) => /^[-*+]\s+/.test(line.trim())) + .map((line) => normalizeBullet(line)); +} + +interface BulletMatch { + index: number; + normalized: string; +} + +function bulletPreview(text: string): string { + return text.length > PREVIEW_CHARS + ? `${text.slice(0, PREVIEW_CHARS - 1).trimEnd()}…` + : text; +} + +function findBulletMatches(lines: string[], span: SectionSpan, needle: string): BulletMatch[] { + const out: BulletMatch[] = []; + for (let i = span.bodyStart; i < span.bodyEnd; i += 1) { + const line = lines[i]!; + if (!/^[-*+]\s+/.test(line.trim())) continue; + if (line.toLowerCase().includes(needle)) { + out.push({ index: i, normalized: normalizeBullet(line) }); + } + } + return out; +} + +function readLines(path: string): string[] { + if (!existsSync(path)) return []; + const content = readFileSync(path, "utf8").replace(/\r/g, ""); + const lines = content.split("\n"); + if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop(); + return lines; +} + +function writeLines(path: string, lines: string[]): void { + mkdirSync(dirname(path), { recursive: true }); + const tempPath = join( + dirname(path), + `.${basename(path)}.${process.pid}.${Date.now()}.tmp`, + ); + writeFileSync(tempPath, lines.join("\n") + "\n", "utf8"); + renameSync(tempPath, path); +} + +function sleepMs(ms: number): void { + Atomics.wait(LOCK_SLEEP_ARRAY, 0, 0, ms); +} + +function withFileLock(path: string, fn: () => T): T { + mkdirSync(dirname(path), { recursive: true }); + const lockPath = `${path}.lock`; + const deadline = Date.now() + LOCK_TIMEOUT_MS; + + while (true) { + let fd: number | null = null; + try { + fd = openSync(lockPath, "wx"); + try { + return fn(); + } finally { + closeSync(fd); + fd = null; + rmSync(lockPath, { force: true }); + } + } catch (error: unknown) { + if (fd !== null) { + try { closeSync(fd); } catch { /* ignore */ } + } + const code = (error as NodeJS.ErrnoException)?.code; + if (code !== "EEXIST") throw error; + + try { + const ageMs = Date.now() - statSync(lockPath).mtimeMs; + if (ageMs > STALE_LOCK_MS) { + rmSync(lockPath, { force: true }); + continue; + } + } catch { + // statSync failed — most commonly because the lock holder released + // the lockfile between our openSync and statSync. Retry the loop; + // we'll likely acquire the lock on the next iteration. + continue; + } + + if (Date.now() >= deadline) { + throw new Error(`Timed out waiting for memory lock: ${lockPath}`); + } + sleepMs(LOCK_POLL_MS); + } + } +} + +function assertBullet(bullet: string): string { + const normalized = normalizeBullet(bullet); + if (!normalized) throw new Error("Bullet text must be non-empty"); + return normalized; +} + +export interface EditOptions { + root: string; + file: EditableFile; + section: string; +} + +export function addBullet( + options: EditOptions, + bullet: string, +): UpdateResult { + const path = join(options.root, options.file); + const normalized = assertBullet(bullet); + return withFileLock(path, () => { + const lines = readLines(path); + const seededLines = lines.length === 0 + ? seedEmptyEditableFile(options.file, options.section) + : lines; + + const span = findSection(seededLines, options.section); + if (!span) { + return { action: { kind: "missing_section", section: options.section }, file: path }; + } + + const existing = new Set(bulletsInSpan(seededLines, span)); + if (existing.has(normalized)) { + return { action: { kind: "noop", reason: "duplicate" }, file: path }; + } + + const insertAt = span.bodyEnd; + const nextLines = [ + ...seededLines.slice(0, insertAt), + normalized, + ...seededLines.slice(insertAt), + ]; + writeLines(path, nextLines); + return { action: { kind: "added" }, file: path }; + }); +} + +export function replaceBullet( + options: EditOptions, + match: string, + replacement: string, +): UpdateResult { + const path = join(options.root, options.file); + const normalizedReplacement = assertBullet(replacement); + const needle = String(match || "").trim().toLowerCase(); + if (!needle) throw new Error("--match is required for replace"); + return withFileLock(path, () => { + const lines = readLines(path); + const span = findSection(lines, options.section); + if (!span) { + return { action: { kind: "missing_section", section: options.section }, file: path }; + } + + const matches = findBulletMatches(lines, span, needle); + if (matches.length === 0) { + return { action: { kind: "missing_match", match }, file: path }; + } + + const uniqueMatches = new Set(matches.map((entry) => entry.normalized)); + if (uniqueMatches.size > 1) { + return { + action: { + kind: "ambiguous_match", + match, + candidates: Array.from(uniqueMatches, (entry) => bulletPreview(entry)), + }, + file: path, + }; + } + + const matchIndex = matches[0]!.index; + const currentNormalized = matches[0]!.normalized; + if (currentNormalized === normalizedReplacement) { + return { action: { kind: "noop", reason: "duplicate" }, file: path }; + } + + const replacementExists = matchesInSpan(lines, span, normalizedReplacement) + .some((index) => index !== matchIndex); + if (replacementExists) { + lines.splice(matchIndex, 1); + writeLines(path, lines); + return { action: { kind: "deduped" }, file: path }; + } + + lines[matchIndex] = normalizedReplacement; + writeLines(path, lines); + return { action: { kind: "replaced" }, file: path }; + }); +} + +export function removeBullet( + options: EditOptions, + match: string, +): UpdateResult { + const path = join(options.root, options.file); + const needle = String(match || "").trim().toLowerCase(); + if (!needle) throw new Error("--match is required for remove"); + return withFileLock(path, () => { + const lines = readLines(path); + const span = findSection(lines, options.section); + if (!span) { + return { action: { kind: "missing_section", section: options.section }, file: path }; + } + + const matches = findBulletMatches(lines, span, needle); + if (matches.length === 0) { + return { action: { kind: "missing_match", match }, file: path }; + } + + const uniqueMatches = new Set(matches.map((entry) => entry.normalized)); + if (uniqueMatches.size > 1) { + return { + action: { + kind: "ambiguous_match", + match, + candidates: Array.from(uniqueMatches, (entry) => bulletPreview(entry)), + }, + file: path, + }; + } + + lines.splice(matches[0]!.index, 1); + writeLines(path, lines); + return { action: { kind: "removed" }, file: path }; + }); +} + +export function todayDateUtc(now = new Date()): string { + const year = now.getUTCFullYear(); + const month = String(now.getUTCMonth() + 1).padStart(2, "0"); + const day = String(now.getUTCDate()).padStart(2, "0"); + return `${year}-${month}-${day}`; +} + +export function dailyLogPath(root: string, date: string): string { + return join(root, DAILY_DIR, `${date}.md`); +} + +function ensureDailyLog(path: string, date: string): string[] { + if (existsSync(path)) return readLines(path); + const lines = [ + `# Daily log for ${date}`, + "", + sectionHeader(DAILY_ACTIVITY_SECTION), + ]; + writeLines(path, lines); + return lines; +} + +export function appendDailyBullet( + root: string, + bullet: string, + dateOverride?: string, +): UpdateResult { + const date = dateOverride || todayDateUtc(); + const path = dailyLogPath(root, date); + const normalized = assertBullet(bullet); + return withFileLock(path, () => { + const lines = ensureDailyLog(path, date); + + const span = findSection(lines, DAILY_ACTIVITY_SECTION); + if (!span) { + // ensureDailyLog just wrote the header, so this is a structural bug. + throw new Error(`Daily log at ${path} is missing section: ${DAILY_ACTIVITY_SECTION}`); + } + + const existing = new Set(bulletsInSpan(lines, span)); + if (existing.has(normalized)) { + return { action: { kind: "noop", reason: "duplicate" }, file: path }; + } + + const insertAt = span.bodyEnd; + const nextLines = [ + ...lines.slice(0, insertAt), + normalized, + ...lines.slice(insertAt), + ]; + writeLines(path, nextLines); + return { action: { kind: "added" }, file: path }; + }); +} + +export function isEditableFile(name: string): name is EditableFile { + return name === MEMORY_FILE || name === PROJECT_FILE; +} + +function matchesInSpan(lines: string[], span: SectionSpan, normalizedBullet: string): number[] { + const out: number[] = []; + for (let i = span.bodyStart; i < span.bodyEnd; i += 1) { + const line = lines[i]!; + if (!/^[-*+]\s+/.test(line.trim())) continue; + if (normalizeBullet(line) === normalizedBullet) out.push(i); + } + return out; +} diff --git a/.agent/src/mentions.ts b/.agent/src/mentions.ts new file mode 100644 index 0000000..ab282ae --- /dev/null +++ b/.agent/src/mentions.ts @@ -0,0 +1,42 @@ +// Mention parsing helpers. These functions are intentionally detached from +// any specific GitHub entity so mention-based workflows can reuse the same +// boundary-aware parsing and markdown stripping rules. + +/** + * Escapes user-provided mention text before building a regex around it. + */ +export function escapeRegex(text: string): string { + return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +/** + * Removes quoted and code-only content so mentions inside them do not + * trigger the workflow. + */ +export function stripNonLiveMentions(markdown: string): string { + return markdown + .replace(/```[\s\S]*?```/g, "\n") + .replace(/~~~[\s\S]*?~~~/g, "\n") + .replace(/`[^`\n]*`/g, "") + .split("\n") + .filter((line) => !line.match(/^\s*>/)) + .join("\n"); +} + +/** + * Builds the boundary-aware mention matcher used for the final trigger check. + */ +export function buildMentionRegex(mention: string): RegExp { + return new RegExp( + `(^|[\\s(])${escapeRegex(mention)}(?=[\\s.,;:!?)\\]}]|$)`, + "m", + ); +} + +/** + * Checks whether the markdown contains a live mention after stripping + * quoted and code-only content. + */ +export function hasLiveMention(markdown: string, mention: string): boolean { + return buildMentionRegex(mention).test(stripNonLiveMentions(markdown)); +} diff --git a/.agent/src/onboarding.ts b/.agent/src/onboarding.ts new file mode 100644 index 0000000..84c4dbf --- /dev/null +++ b/.agent/src/onboarding.ts @@ -0,0 +1,264 @@ +import { randomBytes } from "node:crypto"; +import { writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { createIssue, ensureLabel, gh, postIssueComment } from "./github.js"; +import { BUILT_IN_TRIGGER_LABELS } from "./trigger-labels.js"; + +const ONBOARDING_TITLE = "Sepo setup check"; +const COMMENT_MARKER = ""; + +export interface OnboardingOptions { + repo: string; + authMode: string; + provider: string; + providerReason: string; + openaiConfigured: boolean; + claudeConfigured: boolean; + memoryRef: string; + rubricsRef: string; + runUrl: string; + runnerTemp: string; +} + +interface ExistingIssue { + number: number; + title: string; +} + +interface ExistingComment { + id: number; + body: string; +} + +function apiPath(repo: string, suffix: string): string { + return `repos/${repo}/${suffix}`; +} + +function branchExists(repo: string, branch: string): boolean { + const ref = branch.trim(); + if (!ref) return false; + + const output = gh([ + "api", + apiPath(repo, `git/matching-refs/heads/${ref}`), + "--jq", + ".[].ref", + ]); + return output.split(/\r?\n/).some((line) => line.trim() === `refs/heads/${ref}`); +} + +function findExistingOnboardingIssue(repo: string): ExistingIssue | null { + const output = gh([ + "issue", + "list", + "--repo", + repo, + "--state", + "open", + "--search", + `${JSON.stringify(ONBOARDING_TITLE)} in:title`, + "--json", + "number,title", + ]); + const issues = JSON.parse(output) as ExistingIssue[]; + return issues.find((issue) => issue.title === ONBOARDING_TITLE) ?? null; +} + +function createOnboardingIssue(opts: OnboardingOptions): number { + const bodyFile = writeOnboardingIssueBody(opts); + const issueUrl = createIssue({ title: ONBOARDING_TITLE, bodyFile, repo: opts.repo }); + const match = issueUrl.match(/(\d+)$/); + if (!match) { + throw new Error(`Could not parse issue number from ${issueUrl}`); + } + return Number.parseInt(match[1], 10); +} + +function updateOnboardingIssueBody(opts: OnboardingOptions, issueNumber: number): void { + const bodyFile = writeOnboardingIssueBody(opts); + gh(["issue", "edit", String(issueNumber), "--repo", opts.repo, "--body-file", bodyFile]); +} + +function findOnboardingComment(repo: string, issueNumber: number): ExistingComment | null { + const output = gh([ + "api", + apiPath(repo, `issues/${issueNumber}/comments`), + ]); + const comments = JSON.parse(output) as ExistingComment[]; + return comments.find((comment) => comment.body.includes(COMMENT_MARKER)) ?? null; +} + +function updateIssueComment(repo: string, commentId: number, body: string): void { + gh([ + "api", + "-X", + "PATCH", + apiPath(repo, `issues/comments/${commentId}`), + "-f", + `body=${body}`, + ]); +} + +function issueBody(): string { + return `Use this issue to track Sepo setup for this repository. + +The latest setup status is maintained in the comment below. +`; +} + +function writeOnboardingIssueBody(opts: OnboardingOptions): string { + const bodyFile = join(opts.runnerTemp, `sepo-onboarding-${randomBytes(8).toString("hex")}.md`); + writeFileSync(bodyFile, issueBody(), "utf8"); + return bodyFile; +} + +function authStatusBody(authMode: string): string { + const resolvedMode = authMode.trim(); + if (resolvedMode) { + return `- [x] GitHub App/auth: resolved via \`${resolvedMode}\``; + } + + return [ + "- [ ] GitHub App/auth: not resolved", + " - Install the Sepo GitHub App or configure a supported auth path.", + ].join("\n"); +} + +function credentialNames(opts: OnboardingOptions): string[] { + const names: string[] = []; + if (opts.openaiConfigured) names.push("`OPENAI_API_KEY`"); + if (opts.claudeConfigured) names.push("`CLAUDE_CODE_OAUTH_TOKEN`"); + return names; +} + +function andList(items: string[]): string { + if (items.length <= 1) return items[0] || ""; + return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`; +} + +function providerDetailBody(opts: OnboardingOptions): string[] { + const provider = opts.provider.trim(); + if (!provider) return []; + + const reason = opts.providerReason.trim(); + return [` - Agent provider: \`${provider}\`${reason ? ` (${reason})` : ""}`]; +} + +function modelStatusBody(opts: OnboardingOptions): string { + const names = credentialNames(opts); + if (names.length === 0) { + return [ + "- [ ] Model credentials: not configured", + " - Add `OPENAI_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret.", + " - Optional: configure `AGENT_DEFAULT_PROVIDER`.", + ...providerDetailBody(opts), + ].join("\n"); + } + + return [ + `- [x] Model credentials: ${andList(names)} configured`, + ...providerDetailBody(opts), + ].join("\n"); +} + +function branchStatusBody(label: string, ref: string, ready: boolean, actionName: string, optional = false): string { + if (ready) { + return `- [x] ${label}: initialized (\`${ref}\`)`; + } + + const prefix = optional ? "Optional: run" : "Run"; + return [ + `- [ ] ${label}: not initialized`, + ` - ${prefix} **Actions > ${actionName}**.`, + ].join("\n"); +} + +function remainingSetupBody(opts: OnboardingOptions, memoryReady: boolean, rubricsReady: boolean): string { + const items: string[] = []; + if (!opts.authMode.trim()) { + items.push("Resolve GitHub App/auth."); + } + if (credentialNames(opts).length === 0) { + items.push("Configure one model provider credential."); + } + if (!memoryReady) { + items.push(`Initialize memory branch \`${opts.memoryRef}\`.`); + } + if (!rubricsReady) { + items.push(`Optional: initialize rubrics branch \`${opts.rubricsRef}\`.`); + } + + if (items.length === 0) { + return "- [x] Required setup is complete."; + } + + return items.map((item) => `- [ ] ${item}`).join("\n"); +} + +function checklistBody(opts: OnboardingOptions, memoryReady: boolean, rubricsReady: boolean): string { + return `${COMMENT_MARKER} +## Sepo setup status + +### Current status + +${authStatusBody(opts.authMode)} +${modelStatusBody(opts)} +${branchStatusBody("Memory", opts.memoryRef, memoryReady, "Agent / Memory / Initialization")} +${branchStatusBody("Rubrics", opts.rubricsRef, rubricsReady, "Agent / Rubrics / Initialization", true)} + +### Remaining setup + +${remainingSetupBody(opts, memoryReady, rubricsReady)} + +### Test Sepo + +After setup, try: + +\`\`\`md +@sepo-agent /answer Is Sepo configured correctly in this repository? +\`\`\` + +Try implementation: + +\`\`\`md +@sepo-agent /implement Create a small README update that verifies the agent can open a PR. +\`\`\` + +On an open pull request: + +\`\`\`md +@sepo-agent /review +\`\`\` + +Last checked: ${opts.runUrl || "GitHub Actions"} +`; +} + +export function runOnboardingCheck(opts: OnboardingOptions): number { + for (const label of BUILT_IN_TRIGGER_LABELS) { + ensureLabel({ + name: label.name, + color: label.color, + description: label.description, + repo: opts.repo, + }); + } + + const memoryReady = branchExists(opts.repo, opts.memoryRef); + const rubricsReady = branchExists(opts.repo, opts.rubricsRef); + const existingIssue = findExistingOnboardingIssue(opts.repo); + const issueNumber = existingIssue?.number ?? createOnboardingIssue(opts); + if (existingIssue) { + updateOnboardingIssueBody(opts, issueNumber); + } + const body = checklistBody(opts, memoryReady, rubricsReady); + const existingComment = findOnboardingComment(opts.repo, issueNumber); + + if (existingComment) { + updateIssueComment(opts.repo, existingComment.id, body); + } else { + postIssueComment(issueNumber, body, opts.repo); + } + + return issueNumber; +} diff --git a/.agent/src/orchestrator-capabilities.ts b/.agent/src/orchestrator-capabilities.ts new file mode 100644 index 0000000..6ff4401 --- /dev/null +++ b/.agent/src/orchestrator-capabilities.ts @@ -0,0 +1,71 @@ +import { + getAllowedAssociationsForRoute, + isAssociationAllowedForRoute, + isKnownAuthorAssociation, + parseAccessPolicy, +} from "./access-policy.js"; + +/** + * Concrete routes that an initial `/orchestrate` request may launch directly or + * through issue-level delegation. + */ +export const ORCHESTRATE_DELEGATED_ROUTES = ["implement", "review", "fix-pr"] as const; + +/** + * Requester and policy context needed to decide whether an initial + * `/orchestrate` start can use the full delegated route capability set. + */ +export interface InitialOrchestrateCapabilityInput { + sourceAction: string; + sourceConclusion: string; + currentRound: number; + allowSelfApprove?: boolean; + allowSelfMerge?: boolean; + authorAssociation: string; + accessPolicy: string; + isPublicRepo: boolean; +} + +function normalizeToken(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +/** + * Returns a user-visible stop reason when an initial `/orchestrate` request + * lacks delegated route capability. Returns an empty string when the check does + * not apply or the requester is authorized. + */ +export function initialOrchestrateCapabilityStopReason(input: InitialOrchestrateCapabilityInput): string { + if ( + normalizeToken(input.sourceAction) !== "orchestrate" || + normalizeToken(input.sourceConclusion) !== "requested" || + input.currentRound !== 1 + ) { + return ""; + } + + let policy; + try { + policy = parseAccessPolicy(input.accessPolicy); + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + return `invalid AGENT_ACCESS_POLICY: ${msg}`; + } + + const association = isKnownAuthorAssociation(input.authorAssociation) ? input.authorAssociation : "NONE"; + const delegatedRoutes: string[] = input.allowSelfApprove + ? [...ORCHESTRATE_DELEGATED_ROUTES, "agent-self-approve"] + : [...ORCHESTRATE_DELEGATED_ROUTES]; + if (input.allowSelfApprove && input.allowSelfMerge) { + delegatedRoutes.push("agent-self-merge"); + } + for (const route of delegatedRoutes) { + if (isAssociationAllowedForRoute(policy, route, association, input.isPublicRepo)) { + continue; + } + const allowed = getAllowedAssociationsForRoute(policy, route, input.isPublicRepo); + return `orchestrate requests require ${route} access; ${route} currently requires ${allowed.join(", ")} access.`; + } + + return ""; +} diff --git a/.agent/src/output.ts b/.agent/src/output.ts new file mode 100644 index 0000000..11900c7 --- /dev/null +++ b/.agent/src/output.ts @@ -0,0 +1,19 @@ +// Shared GitHub Actions output helper. +// +// Uses HEREDOC delimiters for all values, which is safe for multiline +// content. Replaces the per-file setOutput implementations that were +// inconsistent (some used bare key=value, breaking on newlines). + +import { appendFileSync } from "node:fs"; +import { randomBytes } from "node:crypto"; + +/** + * Writes a key-value pair to the GITHUB_OUTPUT file. + * Uses HEREDOC delimiters so multiline values are handled correctly. + */ +export function setOutput(name: string, value: string): void { + const outputFile = process.env.GITHUB_OUTPUT; + if (!outputFile) return; + const delim = `DELIM_${randomBytes(8).toString("hex")}`; + appendFileSync(outputFile, `${name}<<${delim}\n${value}\n${delim}\n`); +} diff --git a/.agent/src/project-management-labels.ts b/.agent/src/project-management-labels.ts new file mode 100644 index 0000000..a91d264 --- /dev/null +++ b/.agent/src/project-management-labels.ts @@ -0,0 +1,117 @@ +import { + addIssueLabel, + addPrLabel, + ensureLabel, + removeIssueLabel, + removePrLabel, +} from "./github.js"; + +export type ProjectItemKind = "issue" | "pull_request"; + +export interface ManagedLabelChange { + kind: ProjectItemKind; + number: number; + add: string[]; + remove: string[]; +} + +export interface ManagedLabelPlan { + label_changes: ManagedLabelChange[]; + valid: boolean; +} + +interface LabelDefinition { + name: string; + color: string; + description: string; +} + +const LABEL_DEFINITIONS: LabelDefinition[] = [ + { name: "priority/p0", color: "b60205", description: "Project management: highest priority" }, + { name: "priority/p1", color: "d93f0b", description: "Project management: high priority" }, + { name: "priority/p2", color: "fbca04", description: "Project management: medium priority" }, + { name: "priority/p3", color: "c2e0c6", description: "Project management: low priority" }, + { name: "effort/low", color: "c2e0c6", description: "Project management: low effort" }, + { name: "effort/medium", color: "fbca04", description: "Project management: medium effort" }, + { name: "effort/high", color: "d73a4a", description: "Project management: high effort" }, +]; + +const MANAGED_LABELS = new Set(LABEL_DEFINITIONS.map((label) => label.name)); + +function asRecord(value: unknown): Record | null { + return value && typeof value === "object" && !Array.isArray(value) ? value as Record : null; +} + +function stringArray(value: unknown): string[] { + if (!Array.isArray(value)) return []; + return value.filter((item): item is string => typeof item === "string").map((item) => item.trim()).filter(Boolean); +} + +function normalizeKind(value: unknown): ProjectItemKind | null { + if (value === "issue" || value === "pull_request") return value; + return null; +} + +function uniqueManagedLabels(labels: string[]): string[] { + return [...new Set(labels)].filter((label) => MANAGED_LABELS.has(label)); +} + +export function parseManagedLabelPlan(markdown: string): ManagedLabelPlan { + const fence = markdown.match(/```json\s*([\s\S]*?)```/i); + if (!fence) return { label_changes: [], valid: false }; + + let parsed: unknown; + try { + parsed = JSON.parse(fence[1]); + } catch { + return { label_changes: [], valid: false }; + } + + const root = asRecord(parsed); + if (!root || !Array.isArray(root.label_changes)) { + return { label_changes: [], valid: false }; + } + + const label_changes: ManagedLabelChange[] = []; + + for (const rawChange of root.label_changes) { + const change = asRecord(rawChange); + if (!change) continue; + const kind = normalizeKind(change.kind); + const number = typeof change.number === "number" && Number.isInteger(change.number) && change.number > 0 + ? change.number + : null; + if (!kind || !number) continue; + + label_changes.push({ + kind, + number, + add: uniqueManagedLabels(stringArray(change.add)), + remove: uniqueManagedLabels(stringArray(change.remove)), + }); + } + + return { label_changes, valid: true }; +} + +export function ensureManagedLabels(repo: string): void { + for (const label of LABEL_DEFINITIONS) { + ensureLabel({ ...label, repo }); + } +} + +export function applyManagedLabelChange(change: ManagedLabelChange, repo: string): void { + for (const label of change.remove) { + if (change.kind === "issue") removeIssueLabel(change.number, label, repo); + else removePrLabel(change.number, label, repo); + } + + for (const label of change.add) { + if (change.kind === "issue") addIssueLabel(change.number, label, repo); + else addPrLabel(change.number, label, repo); + } +} + +export function countManagedLabelOperations(changes: ManagedLabelChange[]): number { + return changes.reduce((total, change) => total + change.add.length + change.remove.length, 0); +} diff --git a/.agent/src/prompt-continuation.ts b/.agent/src/prompt-continuation.ts new file mode 100644 index 0000000..3ce745d --- /dev/null +++ b/.agent/src/prompt-continuation.ts @@ -0,0 +1,28 @@ +export function buildContinuationPrompt(promptVars: Record): string { + return [ + "Trigger metadata:", + `- Triggering source kind: \`${promptVars.REQUEST_SOURCE_KIND || ""}\``, + `- Triggering comment/review ID: \`${promptVars.REQUEST_COMMENT_ID || ""}\``, + `- Triggering comment/review URL: \`${promptVars.REQUEST_COMMENT_URL || ""}\``, + "", + promptVars.REQUEST_TEXT || "", + ].join("\n"); +} + +export function shouldReplayFullPromptOnResume( + route: string, + promptVars: Record, +): boolean { + return route === "fix-pr" && Boolean((promptVars.ORCHESTRATOR_CONTEXT || "").trim()); +} + +export function selectContinuationPromptForResume(options: { + route: string; + promptVars: Record; + continuationPrompt: string; +}): string | undefined { + if (shouldReplayFullPromptOnResume(options.route, options.promptVars)) { + return undefined; + } + return options.continuationPrompt; +} diff --git a/.agent/src/reactions.ts b/.agent/src/reactions.ts new file mode 100644 index 0000000..366dae5 --- /dev/null +++ b/.agent/src/reactions.ts @@ -0,0 +1,33 @@ +// Emoji reactions via GitHub GraphQL API (gh CLI). +// +// Replaces the Octokit-based reactions.cjs with gh api calls, +// consistent with the self-serve pattern in the local runtime's GitHub helpers. + +import { execFileSync } from "node:child_process"; + +const MAX_BUFFER = 10 * 1024 * 1024; + +/** + * Adds a reaction to a GitHub node (issue, comment, PR, etc.). + * @param subjectId - The GraphQL node ID of the subject. + * @param content - The reaction content (e.g., "EYES", "THUMBS_UP"). + */ +export function addReaction(subjectId: string, content: string): void { + const query = ` + mutation($subjectId: ID!, $content: ReactionContent!) { + addReaction(input: { subjectId: $subjectId, content: $content }) { + reaction { content } + } + } + `; + execFileSync( + "gh", + [ + "api", "graphql", + "-f", `query=${query}`, + "-f", `subjectId=${subjectId}`, + "-f", `content=${content}`, + ], + { stdio: "pipe", maxBuffer: MAX_BUFFER }, + ); +} diff --git a/.agent/src/release-version.ts b/.agent/src/release-version.ts new file mode 100644 index 0000000..4b94434 --- /dev/null +++ b/.agent/src/release-version.ts @@ -0,0 +1,33 @@ +const NUMERIC_IDENTIFIER = "(?:0|[1-9][0-9]*)"; +const PRERELEASE_IDENTIFIER = `(?:${NUMERIC_IDENTIFIER}|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)`; +const RELEASE_VERSION_RE = new RegExp( + `^v?(${NUMERIC_IDENTIFIER})\\.(${NUMERIC_IDENTIFIER})\\.(${NUMERIC_IDENTIFIER})(?:-(${PRERELEASE_IDENTIFIER}(?:\\.${PRERELEASE_IDENTIFIER})*))?$`, +); + +export interface ReleaseVersion { + version: string; + tag: string; + major: number; + minor: number; + patch: number; + prereleaseLabel: string; +} + +export function parseReleaseVersion(value: string): ReleaseVersion { + const raw = String(value || "").trim(); + const match = raw.match(RELEASE_VERSION_RE); + if (!match) { + throw new Error("version must be SemVer without build metadata, for example 0.2.0 or 1.0.0-rc.1"); + } + + const [, major, minor, patch, prereleaseLabel = ""] = match; + const version = `${major}.${minor}.${patch}${prereleaseLabel ? `-${prereleaseLabel}` : ""}`; + return { + version, + tag: `v${version}`, + major: Number.parseInt(major, 10), + minor: Number.parseInt(minor, 10), + patch: Number.parseInt(patch, 10), + prereleaseLabel, + }; +} diff --git a/.agent/src/respond.ts b/.agent/src/respond.ts new file mode 100644 index 0000000..59a261c --- /dev/null +++ b/.agent/src/respond.ts @@ -0,0 +1,121 @@ +// Response posting to GitHub surfaces (issues, PRs, discussions). +// +// Uses gh CLI for all API calls, consistent with the local runtime's GitHub helpers. +// Replaces the Octokit-based respond.cjs + post.cjs files. + +import { execFileSync } from "node:child_process"; +import { addDiscussionComment } from "./discussion.js"; +import { postIssueComment, postPrComment } from "./github.js"; + +const MAX_BUFFER = 10 * 1024 * 1024; + +export interface ResponseTarget { + /** "issue_comment" | "review_comment_reply" | "discussion_comment" */ + responseKind: string; + /** Issue, PR, or discussion number */ + targetNumber: number; + /** PR review comment ID (for review_comment_reply) */ + reviewCommentId?: number; + /** Discussion GraphQL node ID (for discussion_comment) */ + discussionNodeId?: string; + /** Optional reply-to node ID for threaded discussion replies */ + replyToId?: string; + /** Repository slug (owner/repo) — used for review comment replies */ + repo?: string; +} + +/** + * Posts a response to the correct GitHub surface based on responseKind. + */ +export function postResponse(target: ResponseTarget, body: string): void { + if (!body.trim()) { + throw new Error("Response body is empty"); + } + + switch (target.responseKind) { + case "issue_comment": + postIssueComment(target.targetNumber, body, target.repo); + break; + + case "pr_comment": + postPrComment(target.targetNumber, body, target.repo); + break; + + case "review_comment_reply": + if (!target.reviewCommentId || !target.repo) { + throw new Error("review_comment_reply requires reviewCommentId and repo"); + } + replyToReviewComment( + target.repo, + target.targetNumber, + target.reviewCommentId, + body, + ); + break; + + case "discussion_comment": + if (!target.discussionNodeId) { + throw new Error("discussion_comment requires discussionNodeId"); + } + if (target.replyToId) { + postDiscussionCommentReply(target.discussionNodeId, body, target.replyToId); + } else { + addDiscussionComment(target.discussionNodeId, body); + } + break; + + default: + throw new Error(`Unsupported response kind: ${target.responseKind}`); + } +} + +/** + * Replies to a PR review comment via REST API. + */ +function replyToReviewComment( + repo: string, + pullNumber: number, + commentId: number, + body: string, +): void { + execFileSync( + "gh", + [ + "api", + "--method", "POST", + `repos/${repo}/pulls/${pullNumber}/comments/${commentId}/replies`, + "-f", `body=${body}`, + ], + { stdio: "pipe", maxBuffer: MAX_BUFFER }, + ); +} + +/** + * Posts a comment to a GitHub discussion via GraphQL. + */ +function postDiscussionCommentReply( + discussionId: string, + body: string, + replyToId: string, +): void { + const query = ` + mutation($discussionId: ID!, $body: String!, $replyToId: ID!) { + addDiscussionComment(input: { + discussionId: $discussionId, + body: $body, + replyToId: $replyToId + }) { + comment { url } + } + } + `; + const args = [ + "api", "graphql", + "-f", `query=${query}`, + "-f", `discussionId=${discussionId}`, + "-f", `body=${body}`, + "-f", `replyToId=${replyToId}`, + ]; + + execFileSync("gh", args, { stdio: "pipe", maxBuffer: MAX_BUFFER }); +} diff --git a/.agent/src/response.ts b/.agent/src/response.ts new file mode 100644 index 0000000..9ddbc9e --- /dev/null +++ b/.agent/src/response.ts @@ -0,0 +1,275 @@ +// Agent response parsing and status determination. + +import { + buildReviewSynthesisHeadMarker, + buildReviewSynthesisMarker, + REVIEW_SYNTHESIS_HEADING, +} from "./review-synthesis.js"; +import { buildFixPrStatusMarker } from "./fix-pr-status.js"; + +/** + * Run statuses for post-agent workflow steps. + */ +export type RunStatus = "success" | "no_changes" | "verify_failed" | "failed" | "unsupported"; + +/** + * Determines the run status from agent exit code, change detection, and + * verification result. This is the shared logic currently duplicated in + * agent-implement.yml and agent-fix-pr.yml shell scripts. + */ +export function determineRunStatus( + agentExitCode: number, + hasChanges: boolean, + verifyExitCode: number, + hasBranchUpdate = false, +): RunStatus { + if (agentExitCode !== 0) return "failed"; + if (!hasChanges && !hasBranchUpdate) return "no_changes"; + if (verifyExitCode !== 0) return "verify_failed"; + return "success"; +} + +// --- Status comment templates --- + +export interface StatusCommentData { + status: RunStatus; + summary?: string; + branch?: string; + prUrl?: string; + requestedBy?: string; + approvalCommentUrl?: string; +} + +function formatMention(loginOrHandle: string): string { + const value = String(loginOrHandle || "").trim(); + if (!value) return ""; + return value.startsWith("@") ? value : `@${value}`; +} + +export function formatImplementComment(data: StatusCommentData): string { + switch (data.status) { + case "success": { + const lines = ["**Sepo implementation finished**", ""]; + if (data.branch) lines.push(`- Branch: \`${data.branch}\``); + if (data.prUrl) lines.push(`- Pull request: ${data.prUrl}`); + if (data.approvalCommentUrl) lines.push(`- Approval: ${data.approvalCommentUrl}`); + lines.push("", data.summary ?? ""); + return lines.join("\n"); + } + case "no_changes": + return [ + "**Sepo did not produce code changes for this issue.**", + "", + "Please add more context or restate the request, then re-request implementation.", + "", + data.summary ?? "", + ].join("\n"); + case "verify_failed": + return [ + "**Sepo made changes, but lightweight verification failed.**", + "", + "Inspect the workflow logs before retrying implementation.", + "", + data.summary ?? "", + ].join("\n"); + default: + return [ + "**Sepo could not complete the implementation run.**", + "", + "Inspect the workflow logs and retry if appropriate.", + "", + data.summary ?? "", + ].join("\n"); + } +} + +export function formatFixPrComment(data: StatusCommentData): string { + const marker = buildFixPrStatusMarker(); + switch (data.status) { + case "success": { + let line = `**Sepo pushed fixes for this PR.** Branch: \`${data.branch ?? ""}\`.`; + const requestedBy = data.requestedBy ? formatMention(data.requestedBy) : ""; + if (requestedBy) line += ` Requested by ${requestedBy}.`; + if (data.approvalCommentUrl) line += ` Approval: ${data.approvalCommentUrl}.`; + return [line, "", marker, "", data.summary ?? ""].join("\n"); + } + case "no_changes": + return [ + "**Sepo did not produce code changes for this PR.**", + "", + marker, + "", + "Please add more context or restate the requested fixes, then try again.", + "", + data.summary ?? "", + ].join("\n"); + case "verify_failed": + return [ + "**Sepo made changes, but lightweight verification failed.**", + "", + marker, + "", + "Inspect the workflow logs before retrying the PR fix run.", + "", + data.summary ?? "", + ].join("\n"); + case "unsupported": + return [ + "**Sepo could not update this PR automatically.**", + "", + marker, + "", + "PR fix runs currently support open same-repository pull requests only.", + data.approvalCommentUrl ? `- Approval: ${data.approvalCommentUrl}` : "", + ].filter(Boolean).join("\n"); + default: + return [ + "**Sepo could not complete the PR fix run.**", + "", + marker, + "", + "Inspect the workflow logs and retry if appropriate.", + "", + data.summary ?? "", + ].join("\n"); + } +} + +export function formatReviewComment(data: { + synthesisBody: string; + requestedBy?: string; + approvalCommentUrl?: string; + reviewedHeadSha?: string; +}): string { + const lines = [ + REVIEW_SYNTHESIS_HEADING, + "", + buildReviewSynthesisMarker(), + ]; + const headMarker = buildReviewSynthesisHeadMarker(data.reviewedHeadSha || ""); + if (headMarker) lines.push(headMarker); + lines.push("", "> Dual-agent review by **Claude** and **Codex**."); + if (data.requestedBy) lines.push(`> Requested by @${data.requestedBy}.`); + if (data.approvalCommentUrl) lines.push(`> Approval comment: ${data.approvalCommentUrl}`); + lines.push("", data.synthesisBody); + return lines.join("\n"); +} + +function escapeMarkdownLinkText(text: string): string { + return text.replace(/\\/g, "\\\\").replace(/\]/g, "\\]"); +} + +function formatBranchReference(ref: string, repoSlug?: string): string { + const normalizedRepoSlug = String(repoSlug || "").trim(); + if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalizedRepoSlug)) { + return `\`${ref}\``; + } + const encodedRef = ref.split("/").map(encodeURIComponent).join("/"); + return `[\`${escapeMarkdownLinkText(ref)}\`](https://github.com/${normalizedRepoSlug}/tree/${encodedRef})`; +} + +export function formatRubricsUpdateComment(data: { + prNumber: string | number; + rubricsRef: string; + rubricsCommitted: boolean; + runSucceeded: boolean; + repoSlug?: string; + summary?: string; +}): string { + const prNumber = String(data.prNumber || "").trim() || "unknown"; + const rubricsRef = String(data.rubricsRef || "").trim() || "agent/rubrics"; + const rubricsRefLink = formatBranchReference(rubricsRef, data.repoSlug); + const lines = ["## Rubrics Update", ""]; + + if (!data.runSucceeded) { + lines.push(`Rubrics update did not complete successfully for PR #${prNumber}; inspect the workflow logs.`); + } else if (data.rubricsCommitted) { + lines.push(`Updated ${rubricsRefLink} from PR #${prNumber}.`); + } else { + lines.push(`No changes were committed to ${rubricsRefLink} from PR #${prNumber}.`); + } + + const summary = String(data.summary || "").trim(); + if (summary) { + lines.push("", summary); + } + + return lines.join("\n"); +} + +// --- JSON response parsing --- + +/** + * Extracts the first balanced JSON object from model output. + * Tolerates fenced wrappers and markdown code fences inside string values. + */ +export function extractJsonObject(raw: string): string { + const text = (raw ?? "").trim(); + if (!text) return ""; + + // Try balanced brace extraction first + const start = text.indexOf("{"); + if (start !== -1) { + let depth = 0; + let inString = false; + let escaped = false; + for (let i = start; i < text.length; i++) { + const ch = text[i]; + if (inString) { + if (escaped) { escaped = false; } + else if (ch === "\\") { escaped = true; } + else if (ch === '"') { inString = false; } + continue; + } + if (ch === '"') { inString = true; continue; } + if (ch === "{") { depth++; continue; } + if (ch === "}") { + depth--; + if (depth === 0) return text.slice(start, i + 1); + } + } + } + + // Try fenced code block + const fenced = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i); + if (fenced) return fenced[1].trim(); + + return ""; +} + +export interface ImplementationResponse { + summary: string; + commitMessage: string; + prTitle: string; + prBody: string; +} + +export function summaryFromAgentResponse(route: string, raw: string): string { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (normalizedRoute === "implement" || normalizedRoute === "fix-pr") { + return normalizeImplementationResponse(raw).summary; + } + return String(raw ?? "").trim(); +} + +export function normalizeImplementationResponse(raw: string): ImplementationResponse { + const text = (raw ?? "").trim(); + if (!text) return { summary: "", commitMessage: "", prTitle: "", prBody: "" }; + + const jsonStr = extractJsonObject(text); + if (jsonStr) { + try { + const payload = JSON.parse(jsonStr) as Record; + const commitMessage = String(payload.commit_message ?? "").replace(/\s+/g, " ").trim(); + const prTitle = String(payload.pr_title ?? "").replace(/\s+/g, " ").trim(); + return { + commitMessage, + prBody: String(payload.pr_body ?? "").trim(), + prTitle, + summary: String(payload.summary ?? "").trim() || prTitle, + }; + } catch { /* fall through */ } + } + + return { summary: text, commitMessage: "", prTitle: "", prBody: "" }; +} diff --git a/.agent/src/review-summary-minimize.ts b/.agent/src/review-summary-minimize.ts new file mode 100644 index 0000000..f974614 --- /dev/null +++ b/.agent/src/review-summary-minimize.ts @@ -0,0 +1,455 @@ +import { + createGhGraphqlClient, + type GraphQLClient, +} from "./github-graphql.js"; +import { hasAnyHandoffMarker, parseAnyHandoffMarker } from "./handoff.js"; +import { isFixPrStatusBody } from "./fix-pr-status.js"; +import { isReviewSynthesisBody } from "./review-synthesis.js"; + +type PageInfo = { + hasNextPage: boolean; + endCursor?: string | null; +}; + +type ReviewSummaryNode = { + id?: string | null; + body?: string | null; + isMinimized?: boolean | null; + author?: { + login?: string | null; + } | null; +}; + +type ReviewSummaryConnection = { + nodes?: ReviewSummaryNode[] | null; + pageInfo: PageInfo; +}; + +type ViewerResponse = { + viewer?: { + login?: string | null; + } | null; +}; + +type PullRequestCommentsResponse = { + repository?: { + pullRequest?: { + comments?: ReviewSummaryConnection | null; + } | null; + } | null; +}; + +type PullRequestReviewsResponse = { + repository?: { + pullRequest?: { + reviews?: ReviewSummaryConnection | null; + } | null; + } | null; +}; + +type IssueCommentsResponse = { + repository?: { + issue?: { + comments?: ReviewSummaryConnection | null; + } | null; + } | null; +}; + +type CollapsePreviousReviewSummariesOptions = { + repo: string; + prNumber: number; + client?: GraphQLClient; +}; + +type CollapsePreviousHandoffCommentsOptions = { + repo: string; + targetNumber: number; + targetKind: "issue" | "pull_request"; + excludeCommentId?: string; + currentCreatedAtMs?: number; + client?: GraphQLClient; +}; + +type ReviewBodyMatcher = (body: string) => boolean; + +const VIEWER_QUERY = ` + query ViewerLogin { + viewer { + login + } + } +`; + +const COMMENTS_QUERY = ` + query PullRequestReviewSummaryComments( + $owner: String! + $name: String! + $number: Int! + $after: String + ) { + repository(owner: $owner, name: $name) { + pullRequest(number: $number) { + comments(first: 100, after: $after) { + nodes { + id + body + isMinimized + author { + login + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + } + } +`; + +const REVIEWS_QUERY = ` + query PullRequestReviewSummaries( + $owner: String! + $name: String! + $number: Int! + $after: String + ) { + repository(owner: $owner, name: $name) { + pullRequest(number: $number) { + reviews(first: 100, after: $after) { + nodes { + id + body + isMinimized + author { + login + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + } + } +`; + +const ISSUE_COMMENTS_QUERY = ` + query IssueGeneratedComments( + $owner: String! + $name: String! + $number: Int! + $after: String + ) { + repository(owner: $owner, name: $name) { + issue(number: $number) { + comments(first: 100, after: $after) { + nodes { + id + body + isMinimized + author { + login + } + } + pageInfo { + hasNextPage + endCursor + } + } + } + } + } +`; + +const MINIMIZE_COMMENT_MUTATION = ` + mutation MinimizeReviewSummary($id: ID!, $classifier: ReportedContentClassifiers!) { + minimizeComment(input: { subjectId: $id, classifier: $classifier }) { + minimizedComment { + isMinimized + } + } + } +`; + +function parseRepo(repo: string): { owner: string; name: string } { + const [owner, name] = repo.split("/", 2); + if (!owner || !name) { + throw new Error(`Expected GITHUB_REPOSITORY-style repo slug, got ${JSON.stringify(repo)}`); + } + return { owner, name }; +} + +function normalizeActorLogin(login: string): string { + return String(login || "") + .trim() + .toLowerCase() + .replace(/^app\//i, "") + .replace(/\[bot\]$/i, ""); +} + +function isSameActorLogin(left: string, right: string): boolean { + return normalizeActorLogin(left) === normalizeActorLogin(right); +} + +export function isRubricsReviewBody(body: string): boolean { + return /(?:^|\r?\n)## Rubrics Review(?:\s|$)/.test(body); +} + +function isGeneratedReviewComment( + node: ReviewSummaryNode, + viewerLogin: string, + bodyMatcher: ReviewBodyMatcher, +): boolean { + if (!node.id || node.isMinimized) return false; + if (!isSameActorLogin(node.author?.login || "", viewerLogin)) return false; + return bodyMatcher(node.body || ""); +} + +function fetchViewerLogin(client: GraphQLClient): string { + const data = client.graphql(VIEWER_QUERY, {}); + const login = data.viewer?.login || ""; + if (!login) { + throw new Error("Could not resolve authenticated GitHub viewer login"); + } + return login; +} + +function fetchMatchingNodes( + client: GraphQLClient, + query: string, + connectionName: "comments" | "reviews", + repo: { owner: string; name: string }, + prNumber: number, + viewerLogin: string, + bodyMatcher: ReviewBodyMatcher, +): ReviewSummaryNode[] { + const matches: ReviewSummaryNode[] = []; + let after: string | undefined; + + do { + const data = client.graphql( + query, + { + owner: repo.owner, + name: repo.name, + number: prNumber, + after, + }, + ); + const pullRequest = data.repository?.pullRequest; + const connection = connectionName === "comments" + ? (pullRequest as { comments?: ReviewSummaryConnection | null } | null | undefined)?.comments + : (pullRequest as { reviews?: ReviewSummaryConnection | null } | null | undefined)?.reviews; + if (!connection) return matches; + + for (const node of connection.nodes || []) { + if (isGeneratedReviewComment(node, viewerLogin, bodyMatcher)) { + matches.push(node); + } + } + after = connection.pageInfo.hasNextPage + ? connection.pageInfo.endCursor || undefined + : undefined; + } while (after); + + return matches; +} + +function collapsePreviousMatchingReviewComments( + options: CollapsePreviousReviewSummariesOptions, + bodyMatcher: ReviewBodyMatcher, +): number { + const client = options.client || createGhGraphqlClient(); + const repo = parseRepo(options.repo); + const viewerLogin = fetchViewerLogin(client); + const nodes = [ + ...fetchMatchingNodes( + client, + COMMENTS_QUERY, + "comments", + repo, + options.prNumber, + viewerLogin, + bodyMatcher, + ), + ...fetchMatchingNodes( + client, + REVIEWS_QUERY, + "reviews", + repo, + options.prNumber, + viewerLogin, + bodyMatcher, + ), + ]; + const uniqueNodeIds = Array.from(new Set(nodes.map((node) => node.id).filter(Boolean))) as string[]; + + for (const id of uniqueNodeIds) { + client.graphql(MINIMIZE_COMMENT_MUTATION, { + id, + classifier: "OUTDATED", + }); + } + + return uniqueNodeIds.length; +} + +function collapsePreviousMatchingPrComments( + options: CollapsePreviousReviewSummariesOptions, + bodyMatcher: ReviewBodyMatcher, +): number { + const client = options.client || createGhGraphqlClient(); + const repo = parseRepo(options.repo); + const viewerLogin = fetchViewerLogin(client); + const nodes = fetchMatchingNodes( + client, + COMMENTS_QUERY, + "comments", + repo, + options.prNumber, + viewerLogin, + bodyMatcher, + ); + const uniqueNodeIds = Array.from(new Set(nodes.map((node) => node.id).filter(Boolean))) as string[]; + + for (const id of uniqueNodeIds) { + client.graphql(MINIMIZE_COMMENT_MUTATION, { + id, + classifier: "OUTDATED", + }); + } + + return uniqueNodeIds.length; +} + +function collapsePreviousMatchingHandoffComments( + options: CollapsePreviousHandoffCommentsOptions, +): number { + const client = options.client || createGhGraphqlClient(); + const repo = parseRepo(options.repo); + const viewerLogin = fetchViewerLogin(client); + const nodes = options.targetKind === "issue" + ? fetchMatchingIssueCommentNodes( + client, + repo, + options.targetNumber, + viewerLogin, + hasAnyHandoffMarker, + ) + : fetchMatchingNodes( + client, + COMMENTS_QUERY, + "comments", + repo, + options.targetNumber, + viewerLogin, + hasAnyHandoffMarker, + ); + const excludeCommentId = String(options.excludeCommentId || ""); + const currentFromComment = nodes.find((node) => node.id === excludeCommentId); + const currentMarker = currentFromComment + ? parseAnyHandoffMarker(currentFromComment.body || "") + : null; + const explicitCreatedAtMs = Number(options.currentCreatedAtMs); + const currentCreatedAtMs = Number.isFinite(explicitCreatedAtMs) && explicitCreatedAtMs > 0 + ? explicitCreatedAtMs + : currentMarker?.createdAtMs ?? null; + const uniqueNodeIds = Array.from(new Set( + nodes + .filter((node) => { + if (!node.id || node.id === excludeCommentId) return false; + const marker = parseAnyHandoffMarker(node.body || ""); + if (!marker || marker.state === "pending") return false; + if (currentCreatedAtMs) { + return Boolean(marker.createdAtMs && marker.createdAtMs < currentCreatedAtMs); + } + return true; + }) + .map((node) => node.id) + .filter((id): id is string => Boolean(id)), + )); + + for (const id of uniqueNodeIds) { + client.graphql(MINIMIZE_COMMENT_MUTATION, { + id, + classifier: "OUTDATED", + }); + } + + return uniqueNodeIds.length; +} + +function fetchMatchingIssueCommentNodes( + client: GraphQLClient, + repo: { owner: string; name: string }, + issueNumber: number, + viewerLogin: string, + bodyMatcher: ReviewBodyMatcher, +): ReviewSummaryNode[] { + const matches: ReviewSummaryNode[] = []; + let after: string | undefined; + + do { + const data = client.graphql( + ISSUE_COMMENTS_QUERY, + { + owner: repo.owner, + name: repo.name, + number: issueNumber, + after, + }, + ); + const connection = data.repository?.issue?.comments; + if (!connection) return matches; + + for (const node of connection.nodes || []) { + if (isGeneratedReviewComment(node, viewerLogin, bodyMatcher)) { + matches.push(node); + } + } + after = connection.pageInfo.hasNextPage + ? connection.pageInfo.endCursor || undefined + : undefined; + } while (after); + + return matches; +} + +/** + * Collapses older agent-generated PR review summaries before posting a fresh one. + */ +export function collapsePreviousReviewSummaries( + options: CollapsePreviousReviewSummariesOptions, +): number { + return collapsePreviousMatchingReviewComments(options, isReviewSynthesisBody); +} + +/** + * Collapses older agent-generated rubrics reviews before posting a fresh one. + */ +export function collapsePreviousRubricsReviews( + options: CollapsePreviousReviewSummariesOptions, +): number { + return collapsePreviousMatchingReviewComments(options, isRubricsReviewBody); +} + +/** + * Collapses older agent-generated fix-pr status comments before posting a fresh one. + */ +export function collapsePreviousFixPrComments( + options: CollapsePreviousReviewSummariesOptions, +): number { + return collapsePreviousMatchingPrComments(options, isFixPrStatusBody); +} + +/** + * Collapses older orchestrator handoff marker comments after a fresh dispatch. + */ +export function collapsePreviousHandoffComments( + options: CollapsePreviousHandoffCommentsOptions, +): number { + return collapsePreviousMatchingHandoffComments(options); +} diff --git a/.agent/src/review-synthesis.ts b/.agent/src/review-synthesis.ts new file mode 100644 index 0000000..0b9f960 --- /dev/null +++ b/.agent/src/review-synthesis.ts @@ -0,0 +1,31 @@ +export const REVIEW_SYNTHESIS_HEADING = "## AI Review Synthesis"; +export const REVIEW_SYNTHESIS_MARKER = ""; +export const REVIEW_SYNTHESIS_HEAD_MARKER_PREFIX = "sepo-agent-review-synthesis-head"; + +function escapeRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +const REVIEW_SYNTHESIS_HEAD_MARKER_REGEX = new RegExp( + ``, + "i", +); + +export function buildReviewSynthesisMarker(): string { + return REVIEW_SYNTHESIS_MARKER; +} + +export function buildReviewSynthesisHeadMarker(headSha: string): string { + const normalized = String(headSha || "").trim(); + return normalized ? `` : ""; +} + +export function extractReviewSynthesisHeadSha(body: string): string { + const match = String(body || "").match(REVIEW_SYNTHESIS_HEAD_MARKER_REGEX); + return match ? match[1].trim() : ""; +} + +export function isReviewSynthesisBody(body: string): boolean { + return body.includes(REVIEW_SYNTHESIS_MARKER) + || body.trimStart().startsWith(REVIEW_SYNTHESIS_HEADING); +} diff --git a/.agent/src/rubrics-policy.ts b/.agent/src/rubrics-policy.ts new file mode 100644 index 0000000..c19c4cb --- /dev/null +++ b/.agent/src/rubrics-policy.ts @@ -0,0 +1,115 @@ +// Parses AGENT_RUBRICS_POLICY, the repository-level configuration for which +// routes can read / write the dedicated user rubric branch. +// +// Rubrics are intentionally separate from repository memory: +// - memory captures agent/project continuity and agent-learned context +// - rubrics capture user/team preferences that steer and evaluate agent work +// +// Shape (both sections optional): +// { +// "default_mode": "enabled" | "read-only" | "disabled", +// "route_overrides": { +// "": "enabled" | "read-only" | "disabled", +// ... +// } +// } +// +// Default when empty or unset: every route gets "read-only". The dedicated +// rubrics update workflow opts into "enabled" with rubrics_mode_override. + +export const RUBRICS_MODES = ["enabled", "read-only", "disabled"] as const; +export type RubricsMode = typeof RUBRICS_MODES[number]; +export const DEFAULT_RUBRICS_MODE: RubricsMode = "read-only"; +export const RUBRICS_HARD_DISABLED_ROUTES = ["dispatch"] as const; + +const VALID_MODE_SET: ReadonlySet = new Set(RUBRICS_MODES); +const RUBRICS_HARD_DISABLED_ROUTE_SET: ReadonlySet = new Set(RUBRICS_HARD_DISABLED_ROUTES); +const VALID_ROUTE_KEY = /^[a-z0-9][a-z0-9._-]*$/; + +export interface RubricsPolicy { + defaultMode: RubricsMode; + routeOverrides: Record; +} + +function normalizeMode(value: unknown, label: string): RubricsMode { + const normalized = String(value || "").trim().toLowerCase(); + if (!VALID_MODE_SET.has(normalized)) { + throw new Error( + `${label} must be one of ${RUBRICS_MODES.join(", ")} (got ${normalized || "empty"})`, + ); + } + return normalized as RubricsMode; +} + +export function parseRubricsPolicy(raw: string): RubricsPolicy { + const text = String(raw || "").trim(); + if (!text) { + return { defaultMode: DEFAULT_RUBRICS_MODE, routeOverrides: {} }; + } + + const payload = JSON.parse(text) as Record; + if (!payload || typeof payload !== "object" || Array.isArray(payload)) { + throw new Error("Rubrics policy must be a JSON object"); + } + + const policy: RubricsPolicy = { + defaultMode: DEFAULT_RUBRICS_MODE, + routeOverrides: {}, + }; + + if ("default_mode" in payload) { + policy.defaultMode = normalizeMode(payload.default_mode, "default_mode"); + } + + if ("route_overrides" in payload) { + const overrides = payload.route_overrides; + if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) { + throw new Error("route_overrides must be an object"); + } + for (const [route, mode] of Object.entries(overrides)) { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (!VALID_ROUTE_KEY.test(normalizedRoute)) { + throw new Error( + `Invalid route override key in rubrics policy: ${normalizedRoute || "missing"}`, + ); + } + policy.routeOverrides[normalizedRoute] = normalizeMode( + mode, + `route_overrides.${normalizedRoute}`, + ); + } + } + + return policy; +} + +export function getRubricsModeForRoute( + policy: RubricsPolicy, + route: string, +): RubricsMode { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (isRubricsHardDisabledRoute(normalizedRoute)) { + return "disabled"; + } + if (normalizedRoute && normalizedRoute in policy.routeOverrides) { + return policy.routeOverrides[normalizedRoute]!; + } + return policy.defaultMode; +} + +export function isRubricsHardDisabledRoute(route: string): boolean { + const normalizedRoute = String(route || "").trim().toLowerCase(); + return RUBRICS_HARD_DISABLED_ROUTE_SET.has(normalizedRoute); +} + +export function rubricsModeAllowsRead(mode: RubricsMode): boolean { + return mode !== "disabled"; +} + +export function rubricsModeAllowsWrite(mode: RubricsMode): boolean { + return mode === "enabled"; +} + +export function isRubricsMode(value: unknown): value is RubricsMode { + return typeof value === "string" && VALID_MODE_SET.has(value); +} diff --git a/.agent/src/rubrics.ts b/.agent/src/rubrics.ts new file mode 100644 index 0000000..14d65b2 --- /dev/null +++ b/.agent/src/rubrics.ts @@ -0,0 +1,383 @@ +// Rubric storage and retrieval helpers. +// +// Rubrics are user/team-owned normative preferences, stored on a dedicated +// agent/rubrics branch. They are deliberately separate from agent memory: +// memory records context the agent learns; rubrics encode what users want the +// agent to optimize for and be reviewed against. + +import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; +import { dirname, extname, join, relative, resolve, sep } from "node:path"; +import YAML from "yaml"; + +export const RUBRICS_SCHEMA_VERSION = 1; +export const RUBRICS_ROOT_DIR = "rubrics"; +export const RUBRICS_README = "README.md"; + +export const RUBRIC_TYPES = ["generic", "specific"] as const; +export type RubricType = typeof RUBRIC_TYPES[number]; + +export const RUBRIC_DOMAINS = [ + "coding_style", + "coding_workflow", + "communication", + "review_quality", +] as const; +export type RubricDomain = typeof RUBRIC_DOMAINS[number]; + +export const RUBRIC_SEVERITIES = ["must", "should", "consider"] as const; +export type RubricSeverity = typeof RUBRIC_SEVERITIES[number]; + +export const RUBRIC_STATUSES = ["active", "draft", "retired"] as const; +export type RubricStatus = typeof RUBRIC_STATUSES[number]; + +export const RUBRIC_ROUTE_NAMES = [ + "answer", + "implement", + "create-action", + "fix-pr", + "review", + "skill", + "rubrics-review", + "rubrics-initialization", + "rubrics-update", +] as const; +export type RubricRouteName = typeof RUBRIC_ROUTE_NAMES[number]; + +export interface RubricExample { + source: string; + note: string; +} + +export interface Rubric { + schema_version: number; + id: string; + title: string; + description: string; + type: RubricType; + domain: RubricDomain; + applies_to: RubricRouteName[]; + severity: RubricSeverity; + weight: number; + status: RubricStatus; + examples: RubricExample[]; + path: string; + absolutePath: string; +} + +export interface RubricValidationError { + path: string; + message: string; +} + +export interface RubricLoadResult { + rubrics: Rubric[]; + errors: RubricValidationError[]; +} + +export interface RubricSelectionResult { + rubric: Rubric; + score: number; + matchedTerms: string[]; +} + +export interface RubricSearchOptions { + rootDir: string; + route: string; + query?: string; + limit?: number; + includeDraft?: boolean; + allRoutes?: boolean; + domains?: RubricDomain[]; +} + +const VALID_ID = /^[a-z0-9][a-z0-9-]*$/; +const DEFAULT_LIMIT = 10; +const VALID_TYPE_SET = new Set(RUBRIC_TYPES); +const VALID_DOMAIN_SET = new Set(RUBRIC_DOMAINS); +const VALID_SEVERITY_SET = new Set(RUBRIC_SEVERITIES); +const VALID_STATUS_SET = new Set(RUBRIC_STATUSES); +const VALID_ROUTE_SET = new Set(RUBRIC_ROUTE_NAMES); + +function toPosixPath(value: string): string { + return value.split(sep).join("/"); +} + +function ensureDirectory(path: string): void { + mkdirSync(path, { recursive: true }); +} + +function ensureFile(path: string, content: string, createdFiles: string[]): void { + if (existsSync(path)) return; + ensureDirectory(dirname(path)); + writeFileSync(path, content, "utf8"); + createdFiles.push(path); +} + +export interface EnsureRubricsStructureResult { + createdFiles: string[]; +} + +export function ensureRubricsStructure(rootDir: string, repoSlug: string): EnsureRubricsStructureResult { + const createdFiles: string[] = []; + const root = resolve(rootDir); + + for (const domain of ["coding", "communication", "workflow"] as const) { + ensureDirectory(join(root, RUBRICS_ROOT_DIR, domain)); + ensureFile(join(root, RUBRICS_ROOT_DIR, domain, ".gitkeep"), "", createdFiles); + } + + ensureFile( + join(root, RUBRICS_README), + [ + "# Agent rubrics", + "", + `This branch stores user/team-owned rubrics for ${repoSlug || "this repository"}.`, + "", + "Rubrics are normative preferences used to steer implementation and evaluate reviews.", + "They are separate from `agent/memory`, which stores agent/project continuity.", + "", + "Each active rubric is a YAML file under `rubrics/`.", + "", + ].join("\n"), + createdFiles, + ); + + return { createdFiles }; +} + +function collectYamlFiles(rootDir: string): string[] { + const root = resolve(rootDir); + const rubricsRoot = join(root, RUBRICS_ROOT_DIR); + if (!existsSync(rubricsRoot)) return []; + + const out: string[] = []; + const stack = [rubricsRoot]; + while (stack.length > 0) { + const current = stack.pop()!; + let entries; + try { + entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); + } catch { + continue; + } + + for (const entry of entries) { + const full = join(current, entry.name); + if (entry.isDirectory()) { + if (entry.name === ".git") continue; + stack.push(full); + continue; + } + const ext = extname(entry.name).toLowerCase(); + if (entry.isFile() && (ext === ".yaml" || ext === ".yml")) { + out.push(full); + } + } + } + return out.sort(); +} + +function normalizeString(value: unknown): string { + return String(value || "").trim(); +} + +function normalizeStringArray(value: unknown): string[] { + if (!Array.isArray(value)) return []; + return value.map((entry) => normalizeString(entry)).filter(Boolean); +} + +function normalizeExamples(value: unknown): RubricExample[] { + if (!Array.isArray(value)) return []; + const examples: RubricExample[] = []; + for (const entry of value) { + if (!entry || typeof entry !== "object") continue; + const record = entry as Record; + const source = normalizeString(record.source); + const note = normalizeString(record.note); + if (source || note) examples.push({ source, note }); + } + return examples; +} + +function parseRubricYaml(filePath: string, rootDir: string): Rubric { + const raw = readFileSync(filePath, "utf8"); + const parsed = YAML.parse(raw) as Record; + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { + throw new Error("rubric YAML must be an object"); + } + + const schemaVersion = parsed.schema_version === undefined + ? RUBRICS_SCHEMA_VERSION + : Number(parsed.schema_version); + const id = normalizeString(parsed.id); + const title = normalizeString(parsed.title); + const description = normalizeString(parsed.description); + const type = normalizeString(parsed.type || "generic").toLowerCase(); + const rawDomain = normalizeString(parsed.domain || parsed.category || "coding_workflow").toLowerCase(); + const domain = rawDomain === "coding" ? "coding_workflow" : rawDomain; + const severity = normalizeString(parsed.severity || "should").toLowerCase(); + const status = normalizeString(parsed.status || "active").toLowerCase(); + const appliesTo = normalizeStringArray(parsed.applies_to).map((route) => route.toLowerCase()); + const weight = parsed.weight === undefined ? 1 : Number(parsed.weight); + + if (schemaVersion !== RUBRICS_SCHEMA_VERSION) throw new Error(`schema_version must be ${RUBRICS_SCHEMA_VERSION}`); + if (!id || !VALID_ID.test(id)) throw new Error("id must be kebab-case and start with a letter or digit"); + if (!title) throw new Error("title is required"); + if (!description) throw new Error("description is required"); + if (!VALID_TYPE_SET.has(type)) throw new Error(`type must be one of ${RUBRIC_TYPES.join(", ")}`); + if (!VALID_DOMAIN_SET.has(domain)) throw new Error(`domain must be one of ${RUBRIC_DOMAINS.join(", ")}`); + if (!VALID_SEVERITY_SET.has(severity)) throw new Error(`severity must be one of ${RUBRIC_SEVERITIES.join(", ")}`); + if (!VALID_STATUS_SET.has(status)) throw new Error(`status must be one of ${RUBRIC_STATUSES.join(", ")}`); + if (!Number.isInteger(weight) || weight < 1 || weight > 10) throw new Error("weight must be an integer from 1 to 10"); + if (appliesTo.length === 0) throw new Error("applies_to must contain at least one route"); + for (const route of appliesTo) { + if (!VALID_ROUTE_SET.has(route)) throw new Error(`unsupported applies_to route: ${route}`); + } + + return { + schema_version: schemaVersion, + id, + title, + description, + type: type as RubricType, + domain: domain as RubricDomain, + applies_to: [...new Set(appliesTo)] as RubricRouteName[], + severity: severity as RubricSeverity, + weight, + status: status as RubricStatus, + examples: normalizeExamples(parsed.examples), + path: toPosixPath(relative(resolve(rootDir), filePath)), + absolutePath: filePath, + }; +} + +export function loadRubrics(rootDir: string): RubricLoadResult { + const files = collectYamlFiles(rootDir); + const rubrics: Rubric[] = []; + const errors: RubricValidationError[] = []; + const seenIds = new Map(); + + for (const file of files) { + try { + const rubric = parseRubricYaml(file, rootDir); + const previous = seenIds.get(rubric.id); + if (previous) { + errors.push({ path: rubric.path, message: `duplicate id ${rubric.id} also used by ${previous}` }); + continue; + } + seenIds.set(rubric.id, rubric.path); + rubrics.push(rubric); + } catch (err: unknown) { + errors.push({ + path: toPosixPath(relative(resolve(rootDir), file)), + message: err instanceof Error ? err.message : String(err), + }); + } + } + + return { rubrics: rubrics.sort((a, b) => a.id.localeCompare(b.id)), errors }; +} + +export function tokenizeRubricQuery(query: string): string[] { + const seen = new Set(); + return String(query || "") + .trim() + .toLowerCase() + .split(/[^a-z0-9]+/i) + .map((token) => token.trim()) + .filter((token) => token.length >= 3 || /^[0-9]+$/.test(token)) + .filter((token) => { + if (seen.has(token)) return false; + seen.add(token); + return true; + }); +} + +function searchableText(rubric: Rubric): string { + return [ + rubric.id, + rubric.title, + rubric.description, + rubric.type, + rubric.domain, + rubric.severity, + ...rubric.applies_to, + ...rubric.examples.flatMap((example) => [example.source, example.note]), + ].join("\n").toLowerCase(); +} + +function routeMatches(rubric: Rubric, route: string): boolean { + const normalized = String(route || "").trim().toLowerCase(); + if (!normalized) return true; + if (rubric.applies_to.includes(normalized as RubricRouteName)) return true; + // Rubrics for implementation also apply to the PR-fix implementation path + // unless the author chose a more specific route list. + return normalized === "fix-pr" && rubric.applies_to.includes("implement"); +} + +function severityScore(severity: RubricSeverity): number { + switch (severity) { + case "must": return 30; + case "should": return 20; + case "consider": return 10; + } +} + +export function selectRubrics(options: RubricSearchOptions): { selected: RubricSelectionResult[]; errors: RubricValidationError[] } { + const { rubrics, errors } = loadRubrics(options.rootDir); + const tokens = tokenizeRubricQuery(options.query || ""); + const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT); + const domainFilter = new Set(options.domains || []); + const selected: RubricSelectionResult[] = []; + + for (const rubric of rubrics) { + if (rubric.status === "retired") continue; + if (rubric.status === "draft" && !options.includeDraft) continue; + if (!options.allRoutes && !routeMatches(rubric, options.route)) continue; + if (domainFilter.size > 0 && !domainFilter.has(rubric.domain)) continue; + + const text = searchableText(rubric); + const matchedTerms: string[] = []; + let score = severityScore(rubric.severity) + rubric.weight * 2; + for (const token of tokens) { + if (text.includes(token)) { + matchedTerms.push(token); + score += Math.max(token.length, 3) * 3; + } + } + + // With an empty or sparse query, active route-applicable rubrics are still + // useful as baseline steering; rank by severity and weight. + selected.push({ rubric, score, matchedTerms }); + } + + selected.sort((a, b) => b.score - a.score || b.rubric.weight - a.rubric.weight || a.rubric.id.localeCompare(b.rubric.id)); + return { selected: Number.isFinite(limit) ? selected.slice(0, limit) : selected, errors }; +} + +export function formatRubricsForPrompt(selected: RubricSelectionResult[]): string { + if (selected.length === 0) { + return "No active route-applicable rubrics were selected for this run."; + } + + const lines: string[] = []; + for (const entry of selected) { + const rubric = entry.rubric; + lines.push(`### ${rubric.title}`); + lines.push(`- id: \`${rubric.id}\``); + lines.push(`- domain/type: ${rubric.domain} / ${rubric.type}`); + lines.push(`- severity/weight: ${rubric.severity} / ${rubric.weight}`); + lines.push(`- applies to: ${rubric.applies_to.join(", ")}`); + lines.push(`- source file: \`${rubric.path}\``); + lines.push(`- rubric: ${rubric.description}`); + if (entry.matchedTerms.length > 0) { + lines.push(`- matched terms: ${entry.matchedTerms.join(", ")}`); + } + if (rubric.examples.length > 0) { + const example = rubric.examples[0]!; + lines.push(`- provenance: ${[example.source, example.note].filter(Boolean).join(" — ")}`); + } + lines.push(""); + } + return lines.join("\n").trimEnd() + "\n"; +} diff --git a/.agent/src/run.ts b/.agent/src/run.ts new file mode 100644 index 0000000..82421de --- /dev/null +++ b/.agent/src/run.ts @@ -0,0 +1,680 @@ +// Agent adapter entrypoint. +// +// Reads a RuntimeEnvelope from environment variables, validates it, renders +// the prompt template (base + route), runs acpx directly, and outputs the +// result. + +import { readFileSync, writeFileSync, existsSync, statSync } from "node:fs"; +import { isAbsolute, join, resolve } from "node:path"; +import { randomBytes } from "node:crypto"; + +import { + type RuntimeEnvelope, + buildEnvelope, + validateEnvelope, + envelopeToPromptVars, +} from "./envelope.js"; +import { + preflight, + runAcpx, + readSessionIdentityResult, + formatSessionLogForDisplay, + tailForLog, + parsePermissionModeOrSetDefault, +} from "./acpx-adapter.js"; +import { + type ThreadState, + type PushOptions, + getThreadState, + markThreadRunning, + markThreadCompleted, + markThreadFailed, +} from "./thread-state.js"; +import { + type SessionPolicy, + parseSessionPolicy, + sessionModeForPolicy, + tracksThreadState, +} from "./session-policy.js"; +import { + buildRunningThreadStateFields, + buildThreadStateFieldsFromEnsureOutcome, + buildCompletedThreadStateUpdates, + buildFailedThreadStateUpdates, + resumeSessionIdFromForkSource, + resumeSessionIdFromState, + shouldUseContinuationPrompt, + shouldFailRunBecauseOfEnsureOutcome, + shouldFailRunBecauseOfThreadStateError, + shouldFailBecauseRequiredResumeIdentityMissing, +} from "./runtime-state.js"; +import { configureBotIdentity } from "./git.js"; +import { setOutput } from "./output.js"; +import { + buildContinuationPrompt, + selectContinuationPromptForResume, +} from "./prompt-continuation.js"; +import { + parseSessionBundleMode, + shouldBackupSessionBundles, +} from "./session-bundle.js"; + +// --- Logging --- + +function log(level: string, msg: string, extra: Record = {}): void { + const entry = { ts: new Date().toISOString(), level, msg, ...extra }; + process.stderr.write(JSON.stringify(entry) + "\n"); +} + +const SUPPLEMENTAL_PROMPT_VAR_NAMES = [ + "MEMORY_AVAILABLE", + "MEMORY_DIR", + "MEMORY_REF", + "RUBRICS_AVAILABLE", + "RUBRICS_DIR", + "RUBRICS_REF", + "RUBRICS_CONTEXT_FILE", + "REQUEST_COMMENT_ID", + "REQUEST_COMMENT_URL", + "REQUEST_SOURCE_KIND", + "REVIEWS_DIR", + "CLAUDE_REVIEW_FILE", + "CODEX_REVIEW_FILE", + "ORCHESTRATOR_SOURCE_ACTION", + "ORCHESTRATOR_SOURCE_CONCLUSION", + "ORCHESTRATOR_SOURCE_RECOMMENDED_NEXT_STEP", + "ORCHESTRATOR_SOURCE_RUN_ID", + "ORCHESTRATOR_NEXT_TARGET_NUMBER", + "ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT", + "ORCHESTRATOR_SELF_APPROVE_ENABLED", + "ORCHESTRATOR_SELF_MERGE_ENABLED", + "ORCHESTRATOR_CONTEXT", + "ORCHESTRATOR_CURRENT_ROUND", + "ORCHESTRATOR_MAX_ROUNDS", + "SELF_APPROVE_EXPECTED_HEAD_SHA", + "SELF_APPROVE_SOURCE_CONCLUSION", + "SELF_APPROVE_SOURCE_RECOMMENDED_NEXT_STEP", +] as const; + +// --- Envelope from env --- + +function envelopeFromEnv(): RuntimeEnvelope { + return buildEnvelope({ + repo_slug: process.env.REPO_SLUG || "", + route: process.env.ROUTE || "", + source_kind: process.env.SOURCE_KIND || "", + target_kind: process.env.TARGET_KIND || "", + target_number: Number(process.env.TARGET_NUMBER) || 0, + target_url: process.env.TARGET_URL || "", + request_text: process.env.REQUEST_TEXT || process.env.MENTION_BODY || "", + requested_by: process.env.REQUESTED_BY || "", + approval_comment_url: process.env.APPROVAL_COMMENT_URL || null, + workflow: process.env.WORKFLOW || "", + lane: process.env.LANE || "", + }); +} + +// --- Prompt rendering --- + +const BASE_PROMPT_PATH = ".github/prompts/_base.md"; +const MEMORY_PROMPT_PATH = ".github/prompts/_memory.md"; +const RUBRICS_PROMPT_PATH = ".github/prompts/_rubrics.md"; + +const PROMPT_TEMPLATES: Record = { + implement: ".github/prompts/agent-implement.md", + review: ".github/prompts/review.md", + "review-synthesize": ".github/prompts/review-synthesize.md", + "review-synthesize-finalize": ".github/prompts/review-synthesize-finalize.md", + "fix-pr": ".github/prompts/agent-fix-pr.md", + answer: ".github/prompts/agent-answer.md", + "create-action": ".github/prompts/agent-create-action.md", + dispatch: ".github/prompts/agent-dispatch.md", + "rubrics-review": ".github/prompts/rubrics-review.md", + "rubrics-initialization": ".github/prompts/rubrics-initialization.md", + "rubrics-update": ".github/prompts/rubrics-update.md", + orchestrator: ".github/prompts/agent-orchestrator.md", + "agent-self-approve": ".github/prompts/agent-self-approve.md", +}; + +const VALID_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; + +function isRegularFile(path: string): boolean { + try { + return statSync(path).isFile(); + } catch { + return false; + } +} + +function isSafeRelativePath(path: string): boolean { + return path !== "" && !isAbsolute(path) && !path.split(/[\\/]+/).includes(".."); +} + +/** + * Resolves the prompt template path from multiple sources: + * 1. PROMPT_NAME env var → look up in PROMPT_TEMPLATES or .github/prompts/.md + * 2. SKILL_NAME env var → //SKILL.md + * 3. Fall back to route-based lookup in PROMPT_TEMPLATES + */ +function resolveTemplatePath(route: string, repoRoot: string): string | null { + const promptName = process.env.PROMPT_NAME?.trim(); + const skillName = process.env.SKILL_NAME?.trim(); + + if (promptName) { + // Named prompt: check PROMPT_TEMPLATES first, then .github/prompts/.md + if (PROMPT_TEMPLATES[promptName]) { + const p = join(repoRoot, PROMPT_TEMPLATES[promptName]); + if (existsSync(p)) return p; + } + const p = join(repoRoot, ".github", "prompts", `${promptName}.md`); + if (existsSync(p)) return p; + return null; + } + + if (skillName) { + const skillRoot = process.env.SKILL_ROOT?.trim() || ".skills"; + if (!VALID_SKILL_NAME.test(skillName) || !isSafeRelativePath(skillRoot)) return null; + const p = join(repoRoot, skillRoot, skillName, "SKILL.md"); + if (isRegularFile(p)) return p; + return null; + } + + // Default: route-based lookup + const relPath = PROMPT_TEMPLATES[route]; + if (!relPath) return null; + const p = join(repoRoot, relPath); + if (existsSync(p)) return p; + return null; +} + +function renderPrompt( + templatePath: string, + vars: Record, + repoRoot: string, +): string { + const basePath = join(repoRoot, BASE_PROMPT_PATH); + const memoryPath = join(repoRoot, MEMORY_PROMPT_PATH); + const rubricsPath = join(repoRoot, RUBRICS_PROMPT_PATH); + let base = ""; + if (existsSync(basePath)) { + base = readFileSync(basePath, "utf8") + "\n\n"; + } + let memory = ""; + if (vars.MEMORY_AVAILABLE === "true" && existsSync(memoryPath)) { + memory = readFileSync(memoryPath, "utf8") + "\n\n"; + } + let rubrics = ""; + if (vars.RUBRICS_AVAILABLE === "true" && existsSync(rubricsPath)) { + rubrics = readFileSync(rubricsPath, "utf8") + "\n\n"; + } + const template = readFileSync(templatePath, "utf8"); + const combined = base + memory + rubrics + template; + return combined.replace(/\$\{(\w+)\}/g, (_match, key) => vars[key] ?? ""); +} + +// --- Helpers --- + +const FAILURE_OUTPUT_TAIL_CHARS = 4000; + +function sessionPolicyFromEnv(): SessionPolicy { + const parsed = parseSessionPolicy(process.env.SESSION_POLICY); + if (!parsed) { + throw new Error( + "Missing or invalid SESSION_POLICY (expected one of: none, track-only, resume-best-effort, resume-required)", + ); + } + return parsed; +} + +function buildThreadStateOptions(envelope: RuntimeEnvelope): PushOptions { + const opts: PushOptions = { repo: envelope.repo_slug }; + if (process.env.INPUT_GITHUB_TOKEN) { + opts.token = process.env.INPUT_GITHUB_TOKEN; + } + return opts; +} + +function currentRunUrl(): string { + const server = process.env.GITHUB_SERVER_URL; + const repo = process.env.GITHUB_REPOSITORY; + const runId = process.env.GITHUB_RUN_ID; + if (!server || !repo || !runId) { + return ""; + } + return `${server}/${repo}/actions/runs/${runId}`; +} + +function persistFailureOutputFile( + runnerTemp: string, + fileId: string, + suffix: string, + content: string, +): string { + const path = join(runnerTemp, `acpx-${suffix}-${fileId}.log`); + writeFileSync(path, content, "utf8"); + return path; +} + +function persistFailureOutputs( + runnerTemp: string, + fileId: string, + rawStdout: string, + rawStderr: string, +): { rawStdoutFile: string; rawStderrFile: string } { + let rawStdoutFile = ""; + let rawStderrFile = ""; + + if (rawStdout) { + rawStdoutFile = persistFailureOutputFile(runnerTemp, fileId, "stdout", rawStdout); + setOutput("raw_stdout_file", rawStdoutFile); + } + if (rawStderr) { + rawStderrFile = persistFailureOutputFile(runnerTemp, fileId, "stderr", rawStderr); + setOutput("raw_stderr_file", rawStderrFile); + } + + return { rawStdoutFile, rawStderrFile }; +} + +function buildSharedEnv(): Record { + const env: Record = {}; + if (process.env.INPUT_GITHUB_TOKEN) { + env.GH_TOKEN = process.env.INPUT_GITHUB_TOKEN; + env.GITHUB_TOKEN = process.env.INPUT_GITHUB_TOKEN; + } + if (process.env.INPUT_OPENAI_API_KEY) { + env.OPENAI_API_KEY = process.env.INPUT_OPENAI_API_KEY; + } + if (process.env.MODEL_REASONING_EFFORT) { + env.MODEL_REASONING_EFFORT = process.env.MODEL_REASONING_EFFORT; + // Claude Code reads effort from this env var directly, so both the + // flow path and the direct path pick it up without session setup. + env.CLAUDE_CODE_EFFORT_LEVEL = process.env.MODEL_REASONING_EFFORT; + } + if (process.env.CLAUDE_CODE_OAUTH_TOKEN) { + env.CLAUDE_CODE_OAUTH_TOKEN = process.env.CLAUDE_CODE_OAUTH_TOKEN; + } + return env; +} + +// --- Main --- + +function main(): void { + const repoRoot = process.env.GITHUB_WORKSPACE || resolve("."); + const agent = process.env.ACPX_AGENT; + if (!agent) { + log("error", "Missing required ACPX_AGENT"); + process.exitCode = 2; + return; + } + + // 1. Parse envelope + const envelope: RuntimeEnvelope = envelopeFromEnv(); + const errors: string[] = validateEnvelope(envelope); + + if (errors.length > 0) { + log("error", "Envelope validation failed", { errors }); + process.exitCode = 2; + return; + } + + log("info", "Envelope parsed", { + route: envelope.route, + target: `${envelope.target_kind}#${envelope.target_number}`, + thread_key: envelope.thread_key, + }); + + // 2. Resolve prompt template + const templatePath = resolveTemplatePath(envelope.route, repoRoot); + if (!templatePath) { + const source = process.env.PROMPT_NAME || process.env.SKILL_NAME || envelope.route; + log("error", `No prompt template found for: ${source}`); + process.exitCode = 2; + return; + } + + // 3. Render prompt (base + route template) + const promptVars: Record = envelopeToPromptVars(envelope); + + // Supplemental prompt vars from env (route-specific, not part of RuntimeEnvelope). + // Keep this contract explicit so workflows cannot inject arbitrary prompt + // variables without updating the runtime allowlist here. + for (const name of SUPPLEMENTAL_PROMPT_VAR_NAMES) { + if (process.env[name]) promptVars[name] = process.env[name]!; + } + if (promptVars.RUBRICS_CONTEXT_FILE && existsSync(promptVars.RUBRICS_CONTEXT_FILE)) { + promptVars.RUBRICS_CONTEXT = readFileSync(promptVars.RUBRICS_CONTEXT_FILE, "utf8"); + } + // Aliases for backward compat + promptVars.PR_NUMBER = promptVars.TARGET_NUMBER; + promptVars.GITHUB_REPOSITORY = promptVars.REPO_SLUG; + + const prompt = renderPrompt(templatePath, promptVars, repoRoot); + const continuationPrompt = buildContinuationPrompt(promptVars); + const resumeContinuationPrompt = selectContinuationPromptForResume({ + route: envelope.route, + promptVars, + continuationPrompt, + }); + + log("info", "Prompt rendered", { + template: templatePath, + prompt_length: prompt.length, + continuation_prompt_length: continuationPrompt.length, + resume_prompt_mode: resumeContinuationPrompt ? "continuation" : "full", + }); + + // 4. Preflight + const check = preflight(); + if (!check.ok) { + log("error", "Preflight failed: missing tools", { missing: check.missing }); + process.exitCode = 2; + return; + } + + // 5. Common setup + setOutput("prompt", prompt); + setOutput("thread_key", envelope.thread_key); + setOutput("envelope_route", envelope.route); + setOutput("raw_stdout_file", ""); + setOutput("raw_stderr_file", ""); + setOutput("resume_status", "not_attempted"); + setOutput("last_resume_error", ""); + setOutput( + "session_bundle_restore_status", + process.env.SESSION_BUNDLE_RESTORE_STATUS || "not_attempted", + ); + setOutput( + "session_bundle_restore_error", + process.env.SESSION_BUNDLE_RESTORE_ERROR || "", + ); + setOutput("session_fork_from_thread_key", process.env.SESSION_FORK_FROM_THREAD_KEY || ""); + setOutput("session_fork_restore_status", process.env.SESSION_FORK_RESTORE_STATUS || "not_attempted"); + setOutput("session_fork_restore_error", process.env.SESSION_FORK_RESTORE_ERROR || ""); + + const runnerTemp = process.env.RUNNER_TEMP || "/tmp"; + const fileId = randomBytes(8).toString("hex"); + const sharedEnv = buildSharedEnv(); + const permissionMode = parsePermissionModeOrSetDefault(process.env.ACPX_PERMISSION_MODE); + runDirectPath({ + agent, + repoRoot, + prompt, + continuationPrompt: resumeContinuationPrompt, + envelope, + permissionMode, + sharedEnv, + runnerTemp, + fileId, + }); +} + +// --- Direct acpx execution path --- + +function runDirectPath(opts: { + agent: string; + repoRoot: string; + prompt: string; + continuationPrompt?: string; + envelope: RuntimeEnvelope; + permissionMode: "approve-all" | "approve-reads" | "deny-all"; + sharedEnv: Record; + runnerTemp: string; + fileId: string; +}): void { + const { + agent, + repoRoot, + prompt, + continuationPrompt, + envelope, + permissionMode, + sharedEnv, + runnerTemp, + fileId, + } = opts; + let sessionPolicy: SessionPolicy; + try { + sessionPolicy = sessionPolicyFromEnv(); + } catch (err) { + log("error", String(err), { route: envelope.route }); + process.exitCode = 2; + return; + } + const trackThreadState = tracksThreadState(sessionPolicy) && Boolean(envelope.thread_key); + const threadStateOpts = buildThreadStateOptions(envelope); + + let threadState: ThreadState | null = null; + let existingThreadState: ThreadState | null = null; + let resumeSessionId: string | undefined; + let forkResumeSessionId: string | undefined; + let continuationPromptAllowed = false; + const forkFromThreadKey = String(process.env.SESSION_FORK_FROM_THREAD_KEY || "").trim(); + const forkAcpxSessionId = String(process.env.SESSION_FORK_ACPX_SESSION_ID || "").trim(); + + if (trackThreadState) { + try { + configureBotIdentity(repoRoot); + existingThreadState = getThreadState(envelope.thread_key, repoRoot, threadStateOpts); + resumeSessionId = resumeSessionIdFromState(sessionPolicy, existingThreadState); + continuationPromptAllowed = shouldUseContinuationPrompt(existingThreadState, resumeSessionId); + forkResumeSessionId = resumeSessionIdFromForkSource( + sessionPolicy, + existingThreadState, + forkAcpxSessionId, + ); + if (!resumeSessionId && forkResumeSessionId) { + resumeSessionId = forkResumeSessionId; + continuationPromptAllowed = false; + log("info", "Using fork source session as resume seed", { + thread_key: envelope.thread_key, + forked_from_thread_key: forkFromThreadKey, + forked_from_acpx_session_id: forkAcpxSessionId, + }); + } + + if (existingThreadState) { + log("info", "Found existing thread state", { + thread_key: envelope.thread_key, + prior_status: existingThreadState.status, + prior_resume_status: existingThreadState.resume_status, + prior_attempt: existingThreadState.attempt_count, + session_policy: sessionPolicy, + resume_session_id: resumeSessionId ?? null, + }); + } + + threadState = markThreadRunning( + envelope.thread_key, + repoRoot, + { + last_run_url: currentRunUrl(), + ...buildRunningThreadStateFields(), + ...(forkResumeSessionId + ? { + forked_from_thread_key: forkFromThreadKey, + forked_from_acpx_session_id: forkAcpxSessionId, + bundle_restore_status: "restored_from_fork" as const, + last_bundle_restore_error: "", + } + : {}), + }, + threadStateOpts, + ); + log("info", "Thread state marked running", { + thread_key: envelope.thread_key, + attempt: threadState.attempt_count, + session_policy: sessionPolicy, + }); + + if (shouldFailBecauseRequiredResumeIdentityMissing(sessionPolicy, existingThreadState, resumeSessionId)) { + const missingResumeError = "resume-required route has prior thread state but no acpxSessionId to resume"; + setOutput("resume_status", "failed"); + setOutput("last_resume_error", missingResumeError); + const failedUpdates = buildFailedThreadStateUpdates({ + kind: "failed", + error: missingResumeError, + }); + markThreadFailed(envelope.thread_key, threadState, repoRoot, failedUpdates, threadStateOpts); + log("error", "Session continuity requirement not satisfied: prior thread state exists without resumable session identity", { + thread_key: envelope.thread_key, + session_policy: sessionPolicy, + }); + process.exitCode = 1; + return; + } + } catch (err) { + if (shouldFailRunBecauseOfThreadStateError(sessionPolicy)) { + log("error", "Failed to update thread state (pre-run)", { + error: String(err), + session_policy: sessionPolicy, + }); + process.exitCode = 1; + return; + } + log("warn", "Failed to update thread state (pre-run)", { + error: String(err), + session_policy: sessionPolicy, + }); + } + } + + log("info", "Running acpx", { agent, route: envelope.route, permission_mode: permissionMode }); + const sessionBundleMode = parseSessionBundleMode(process.env.SESSION_BUNDLE_MODE); + + const result = runAcpx({ + agent, + prompt, + cwd: repoRoot, + sessionMode: sessionModeForPolicy(sessionPolicy), + threadKey: envelope.thread_key, + permissionMode, + thoughtLevel: process.env.MODEL_REASONING_EFFORT, + preserveExecSession: + sessionPolicy === "track-only" && shouldBackupSessionBundles(sessionBundleMode, sessionPolicy), + preserveExecThoughtLevel: sessionPolicy === "track-only", + resumeSessionId, + continuationPrompt: continuationPromptAllowed ? continuationPrompt : undefined, + env: sharedEnv, + }); + + const resumeFields = buildThreadStateFieldsFromEnsureOutcome(result.sessionEnsureOutcome); + setOutput("resume_status", resumeFields.resume_status); + setOutput("last_resume_error", resumeFields.last_resume_error); + + log("info", "acpx completed", { + exit_code: result.exitCode, + session_name: result.sessionName, + stdout_length: result.stdout.length, + raw_stdout_length: result.rawStdout.length, + stderr_length: result.stderr.length, + session_log_length: result.sessionLog.length, + session_ensure_outcome: result.sessionEnsureOutcome.kind, + }); + + // Display session activity in CI logs + process.stderr.write("\n--- acpx session log ---\n"); + process.stderr.write(formatSessionLogForDisplay(result.sessionLog) + "\n"); + process.stderr.write("--- end session log ---\n\n"); + + // Save session log + const sessionLogFile = join(runnerTemp, `acpx-session-${fileId}.jsonl`); + writeFileSync(sessionLogFile, result.sessionLog, "utf8"); + setOutput("session_log_file", sessionLogFile); + log("info", "Session log saved", { session_log_file: sessionLogFile }); + + // Save response + const responseFile = join(runnerTemp, `acpx-response-${fileId}.md`); + writeFileSync(responseFile, result.stdout, "utf8"); + setOutput("response_file", responseFile); + + let identity: { acpxRecordId: string; acpxSessionId: string } | null = null; + if (result.sessionName) { + setOutput("session_name", result.sessionName); + const identityResult = readSessionIdentityResult(agent, result.sessionName, repoRoot); + identity = identityResult.identity; + if (identity) { + setOutput("acpx_record_id", identity.acpxRecordId); + setOutput("acpx_session_id", identity.acpxSessionId); + log("info", "Session identity", { + acpx_record_id: identity.acpxRecordId, + acpx_session_id: identity.acpxSessionId, + }); + } else { + log("warn", "Session identity could not be read", { + session_name: result.sessionName, + error: identityResult.error, + }); + } + } + + if (trackThreadState && threadState) { + try { + if (result.exitCode !== 0) { + const failedUpdates = buildFailedThreadStateUpdates(result.sessionEnsureOutcome); + markThreadFailed( + envelope.thread_key, + threadState, + repoRoot, + failedUpdates, + threadStateOpts, + ); + log("info", "Thread state marked failed", { + thread_key: envelope.thread_key, + resume_status: failedUpdates.resume_status, + }); + } else { + const updates = buildCompletedThreadStateUpdates({ + outcome: result.sessionEnsureOutcome, + identity: identity ?? null, + }); + markThreadCompleted(envelope.thread_key, threadState, repoRoot, updates, threadStateOpts); + log("info", "Thread state marked completed", { + thread_key: envelope.thread_key, + resume_status: updates.resume_status, + }); + } + } catch (err) { + if (shouldFailRunBecauseOfThreadStateError(sessionPolicy)) { + log("error", "Failed to update thread state (post-run)", { + error: String(err), + session_policy: sessionPolicy, + }); + process.exitCode = 1; + } else { + log("warn", "Failed to update thread state (post-run)", { + error: String(err), + session_policy: sessionPolicy, + }); + } + } + } + + if (shouldFailRunBecauseOfEnsureOutcome(sessionPolicy, result.sessionEnsureOutcome)) { + log("error", "Session continuity requirement not satisfied", { + thread_key: envelope.thread_key, + session_policy: sessionPolicy, + outcome: result.sessionEnsureOutcome, + prior_session_id: existingThreadState?.acpxSessionId || null, + }); + process.exitCode = 1; + } + + if (result.exitCode !== 0) { + const { rawStdoutFile, rawStderrFile } = persistFailureOutputs( + runnerTemp, + fileId, + result.rawStdout, + result.stderr, + ); + log("error", "acpx run failed", { + raw_stdout_file: rawStdoutFile || undefined, + raw_stderr_file: rawStderrFile || undefined, + raw_stdout_tail: tailForLog(result.rawStdout, FAILURE_OUTPUT_TAIL_CHARS), + stderr_tail: tailForLog(result.stderr, FAILURE_OUTPUT_TAIL_CHARS), + }); + process.exitCode = 1; + } +} + +main(); diff --git a/.agent/src/runtime-state.ts b/.agent/src/runtime-state.ts new file mode 100644 index 0000000..fcc8c59 --- /dev/null +++ b/.agent/src/runtime-state.ts @@ -0,0 +1,125 @@ +// Pure helpers for the runtime thread-state state machine. +// +// These helpers are intentionally side-effect free so tests can validate +// session continuity behavior without shelling out to git or acpx. + +import type { SessionEnsureOutcome, SessionIdentity } from "./acpx-adapter.js"; +import type { SessionPolicy } from "./session-policy.js"; +import type { ThreadResumeStatus, ThreadState } from "./thread-state.js"; +import { attemptsResume, requiresResumeContinuity } from "./session-policy.js"; + +export interface ThreadResumeFields { + resume_status: ThreadResumeStatus; + last_resume_error: string; + resumed_from_session_id: string; +} + +export function resumeSessionIdFromState( + policy: SessionPolicy, + state: ThreadState | null, +): string | undefined { + if (!attemptsResume(policy)) { + return undefined; + } + return state?.acpxSessionId || undefined; +} + +export function resumeSessionIdFromForkSource( + policy: SessionPolicy, + existingState: ThreadState | null, + forkAcpxSessionId: string | undefined, +): string | undefined { + if (!attemptsResume(policy) || existingState?.acpxSessionId) { + return undefined; + } + const normalized = String(forkAcpxSessionId || "").trim(); + return normalized || undefined; +} + +export function shouldUseContinuationPrompt( + existingState: ThreadState | null, + resumeSessionId: string | undefined, +): boolean { + return Boolean(existingState?.acpxSessionId && resumeSessionId === existingState.acpxSessionId); +} + +export function buildRunningThreadStateFields(): ThreadResumeFields { + return { + resume_status: "not_attempted", + last_resume_error: "", + resumed_from_session_id: "", + }; +} + +export function buildThreadStateFieldsFromEnsureOutcome( + outcome: SessionEnsureOutcome, +): ThreadResumeFields { + switch (outcome.kind) { + case "resumed": + return { + resume_status: "resumed", + last_resume_error: "", + resumed_from_session_id: outcome.resumedFromSessionId, + }; + case "resume_fallback": + return { + resume_status: "fallback_fresh", + last_resume_error: outcome.error, + resumed_from_session_id: outcome.resumedFromSessionId, + }; + case "failed": + return { + resume_status: "failed", + last_resume_error: outcome.error, + resumed_from_session_id: outcome.resumedFromSessionId || "", + }; + case "fresh": + case "not_applicable": + default: + return buildRunningThreadStateFields(); + } +} + +export function buildCompletedThreadStateUpdates(args: { + outcome: SessionEnsureOutcome; + identity: SessionIdentity | null; +}): Partial { + const updates: Partial = { + ...buildThreadStateFieldsFromEnsureOutcome(args.outcome), + }; + + if (args.identity) { + updates.acpxRecordId = args.identity.acpxRecordId; + updates.acpxSessionId = args.identity.acpxSessionId; + } + + return updates; +} + +export function buildFailedThreadStateUpdates( + outcome: SessionEnsureOutcome, +): Partial { + return buildThreadStateFieldsFromEnsureOutcome(outcome); +} + +export function shouldFailRunBecauseOfEnsureOutcome( + policy: SessionPolicy, + outcome: SessionEnsureOutcome, +): boolean { + if (!requiresResumeContinuity(policy)) { + return false; + } + return outcome.kind === "resume_fallback" || outcome.kind === "failed"; +} + +export function shouldFailRunBecauseOfThreadStateError(policy: SessionPolicy): boolean { + return requiresResumeContinuity(policy); +} + +export function shouldFailBecauseRequiredResumeIdentityMissing( + policy: SessionPolicy, + existingState: ThreadState | null, + resumeSessionId: string | undefined, +): boolean { + return requiresResumeContinuity(policy) && existingState !== null && !resumeSessionId; +} diff --git a/.agent/src/schedule-policy.ts b/.agent/src/schedule-policy.ts new file mode 100644 index 0000000..3ce89b7 --- /dev/null +++ b/.agent/src/schedule-policy.ts @@ -0,0 +1,104 @@ +// Parses AGENT_SCHEDULE_POLICY, the repository-level configuration for +// scheduled workflow runs. +// +// Shape (both sections optional): +// { +// "default_mode": "always_run" | "skip_no_updates" | "disabled", +// "workflow_overrides": { +// "": "always_run" | "skip_no_updates" | "disabled", +// ... +// } +// } + +export const SCHEDULE_MODES = ["always_run", "skip_no_updates", "disabled"] as const; +export type ScheduleMode = typeof SCHEDULE_MODES[number]; +export const DEFAULT_SCHEDULE_MODE: ScheduleMode = "skip_no_updates"; +const BASE_SCHEDULE_WORKFLOW_OVERRIDES: Record = { + "agent-daily-summary.yml": "disabled", +}; +export const DEFAULT_SCHEDULE_WORKFLOW_OVERRIDES: Record = { + ...BASE_SCHEDULE_WORKFLOW_OVERRIDES, + "agent-memory-sync.yml": "always_run", +}; + +const VALID_MODE_SET: ReadonlySet = new Set(SCHEDULE_MODES); +const VALID_WORKFLOW_KEY = /^[a-z0-9][a-z0-9._-]*\.ya?ml$/; + +export interface SchedulePolicy { + defaultMode: ScheduleMode; + workflowOverrides: Record; +} + +function normalizeMode(value: unknown, label: string): ScheduleMode { + const normalized = String(value || "").trim().toLowerCase(); + if (!VALID_MODE_SET.has(normalized)) { + throw new Error( + `${label} must be one of ${SCHEDULE_MODES.join(", ")} (got ${normalized || "empty"})`, + ); + } + return normalized as ScheduleMode; +} + +function normalizeWorkflow(value: string): string { + return String(value || "").trim().toLowerCase(); +} + +export function parseSchedulePolicy(raw: string): SchedulePolicy { + const text = String(raw || "").trim(); + if (!text) { + return { + defaultMode: DEFAULT_SCHEDULE_MODE, + workflowOverrides: { ...DEFAULT_SCHEDULE_WORKFLOW_OVERRIDES }, + }; + } + + const payload = JSON.parse(text) as Record; + if (!payload || typeof payload !== "object" || Array.isArray(payload)) { + throw new Error("Schedule policy must be a JSON object"); + } + + const policy: SchedulePolicy = { + defaultMode: DEFAULT_SCHEDULE_MODE, + workflowOverrides: { ...BASE_SCHEDULE_WORKFLOW_OVERRIDES }, + }; + + if ("default_mode" in payload) { + policy.defaultMode = normalizeMode(payload.default_mode, "default_mode"); + } + + if ("workflow_overrides" in payload) { + const overrides = payload.workflow_overrides; + if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) { + throw new Error("workflow_overrides must be an object"); + } + for (const [workflow, mode] of Object.entries(overrides)) { + const normalizedWorkflow = normalizeWorkflow(workflow); + if (!VALID_WORKFLOW_KEY.test(normalizedWorkflow)) { + throw new Error( + `Invalid workflow override key in schedule policy: ${normalizedWorkflow || "missing"}`, + ); + } + policy.workflowOverrides[normalizedWorkflow] = normalizeMode( + mode, + `workflow_overrides.${normalizedWorkflow}`, + ); + } + } + + return policy; +} + +export function getScheduleModeForWorkflow( + policy: SchedulePolicy, + workflow: string, +): ScheduleMode { + const normalizedWorkflow = normalizeWorkflow(workflow); + if (normalizedWorkflow && normalizedWorkflow in policy.workflowOverrides) { + return policy.workflowOverrides[normalizedWorkflow]!; + } + return policy.defaultMode; +} + +export function isScheduleMode(value: unknown): value is ScheduleMode { + return typeof value === "string" && VALID_MODE_SET.has(value); +} diff --git a/.agent/src/scheduled-activity.ts b/.agent/src/scheduled-activity.ts new file mode 100644 index 0000000..3a049f9 --- /dev/null +++ b/.agent/src/scheduled-activity.ts @@ -0,0 +1,194 @@ +import { buildAuthUrl, git } from "./git.js"; +import { parseSchedulePolicy, getScheduleModeForWorkflow, type ScheduleMode } from "./schedule-policy.js"; + +const STATE_FILENAME = "state.json"; +const REF_NOT_FOUND_PATTERN = /couldn't find remote ref|no matching remote head/i; + +export interface PushOptions { + remote?: string; + token?: string; + repo?: string; +} + +export interface ScheduledActivityGateInput { + eventName: string; + schedulePolicy: string; + workflow: string; + activityCount?: string; + dependencyRef?: string; + dependencyField?: string; + selfRef?: string; + selfField?: string; + cwd?: string; + pushOptions?: PushOptions; +} + +export interface ScheduledActivityGateResult { + skip: boolean; + mode: ScheduleMode; + reason: string; + dependencyValue: string; + selfValue: string; +} + +function resolveRemoteTarget(remote: string, opts?: PushOptions): string { + if (opts?.token && opts?.repo) return buildAuthUrl(opts.token, opts.repo); + return remote; +} + +function readField(record: unknown, field: string): string { + if (!record || typeof record !== "object" || !field) return ""; + const value = (record as Record)[field]; + return typeof value === "string" ? value : ""; +} + +function parseTime(value: string): number | null { + if (!value) return null; + const time = Date.parse(value); + return Number.isFinite(time) ? time : null; +} + +export function resolveCursorActivity( + mode: ScheduleMode, + dependencyValue: string, + selfValue: string, +): ScheduledActivityGateResult { + const dependencyTime = parseTime(dependencyValue); + const selfTime = parseTime(selfValue); + + if (dependencyTime === null || selfTime === null) { + return { + mode, + skip: false, + reason: "missing or invalid activity cursor", + dependencyValue, + selfValue, + }; + } + + if (dependencyTime <= selfTime) { + return { + mode, + skip: true, + reason: "dependency cursor has not advanced", + dependencyValue, + selfValue, + }; + } + + return { + mode, + skip: false, + reason: "dependency cursor advanced", + dependencyValue, + selfValue, + }; +} + +export function fetchJsonState( + ref: string, + cwd: string, + opts?: PushOptions, +): Record | null { + const origin = opts?.remote ?? "origin"; + const fetchTarget = resolveRemoteTarget(origin, opts); + + try { + git(["fetch", "--no-tags", fetchTarget, `+${ref}:${ref}`], cwd); + } catch (err: unknown) { + const stderr = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + if (REF_NOT_FOUND_PATTERN.test(stderr)) return null; + throw err; + } + + try { + const json = git(["cat-file", "blob", `${ref}:${STATE_FILENAME}`], cwd); + const parsed = JSON.parse(json) as unknown; + return parsed && typeof parsed === "object" && !Array.isArray(parsed) + ? (parsed as Record) + : null; + } catch { + return null; + } +} + +export function writeJsonState( + ref: string, + state: Record, + cwd: string, + opts?: PushOptions, +): void { + const origin = opts?.remote ?? "origin"; + const json = JSON.stringify(state, null, 2) + "\n"; + + const blobSha = git(["hash-object", "-w", "--stdin"], cwd, json); + const treeInput = `100644 blob ${blobSha}\t${STATE_FILENAME}\n`; + const treeSha = git(["mktree"], cwd, treeInput); + + let parentArg: string[]; + let expectedOid: string | null = null; + try { + const parentSha = git(["rev-parse", "--verify", ref], cwd); + parentArg = ["-p", parentSha]; + expectedOid = parentSha; + } catch { + parentArg = []; + } + + const commitSha = git(["commit-tree", treeSha, ...parentArg, "-m", `scheduled-state: ${ref}`], cwd); + git(["update-ref", ref, commitSha], cwd); + + const pushTarget = resolveRemoteTarget(origin, opts); + const leaseArg = expectedOid ? `--force-with-lease=${ref}:${expectedOid}` : "--force"; + git(["push", leaseArg, pushTarget, `${ref}:${ref}`], cwd); +} + +export function resolveScheduledActivityGate( + input: ScheduledActivityGateInput, +): ScheduledActivityGateResult { + const policy = parseSchedulePolicy(input.schedulePolicy); + const mode = getScheduleModeForWorkflow(policy, input.workflow); + + const base = { + mode, + dependencyValue: "", + selfValue: "", + }; + + if (input.eventName !== "schedule") { + return { ...base, skip: false, reason: "non-scheduled run" }; + } + if (mode === "disabled") { + return { ...base, skip: true, reason: "schedule policy disabled workflow" }; + } + if (mode === "always_run") { + return { ...base, skip: false, reason: "schedule policy always_run" }; + } + + const dependencyRef = input.dependencyRef || ""; + const dependencyField = input.dependencyField || ""; + const selfRef = input.selfRef || ""; + const selfField = input.selfField || ""; + const activityCount = input.activityCount ?? ""; + if (activityCount.trim()) { + const count = Number(activityCount); + if (Number.isFinite(count) && count <= 0) { + return { ...base, skip: true, reason: "activity count is zero" }; + } + if (Number.isFinite(count) && count > 0) { + return { ...base, skip: false, reason: "activity count is nonzero" }; + } + return { ...base, skip: false, reason: "invalid activity count" }; + } + if (!dependencyRef || !dependencyField || !selfRef || !selfField) { + return { ...base, skip: false, reason: "missing activity cursor configuration" }; + } + + const cwd = input.cwd || process.cwd(); + const dependencyValue = readField( + fetchJsonState(dependencyRef, cwd, input.pushOptions), + dependencyField, + ); + const selfValue = readField(fetchJsonState(selfRef, cwd, input.pushOptions), selfField); + return resolveCursorActivity(mode, dependencyValue, selfValue); +} diff --git a/.agent/src/self-approval.ts b/.agent/src/self-approval.ts new file mode 100644 index 0000000..9b147ac --- /dev/null +++ b/.agent/src/self-approval.ts @@ -0,0 +1,386 @@ +import { extractReviewConclusion, extractReviewRecommendedNextStep } from "./handoff.js"; +import { extractJsonObject } from "./response.js"; +import { + extractReviewSynthesisHeadSha, + isReviewSynthesisBody, +} from "./review-synthesis.js"; + +export type SelfApprovalVerdict = "approve" | "request_changes" | "blocked"; + +export const SELF_APPROVAL_STATUS_MARKER = ""; + +export interface SelfApprovalDecision { + verdict: SelfApprovalVerdict; + reason: string; + handoffContext: string; + inspectedHeadSha: string; +} + +export interface SelfApprovalResolveInput { + allowSelfApprove: boolean; + targetKind: string; + prState: string; + expectedHeadSha: string; + currentHeadSha: string; + decision: SelfApprovalDecision | null; + approvalActorAllowed?: boolean; + approvalActorReason?: string; + approvalProvenanceTrusted?: boolean; + approvalProvenanceReason?: string; +} + +export interface SelfApprovalResolveResult { + conclusion: "approved" | "request_changes" | "blocked" | "failed"; + shouldApprove: boolean; + reason: string; + handoffContext: string; +} + +export interface SelfApprovalSignalComment { + body: string; + authorLogin: string; + createdAt?: string | number | null; +} + +export interface SelfApprovalProvenanceResult { + trusted: boolean; + reason: string; +} + +export interface SelfApprovalActorResult { + allowed: boolean; + reason: string; +} + +function normalizeToken(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +function normalizeActorLogin(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/^app\//i, "") + .replace(/\[bot\]$/i, ""); +} + +function createdAtMs(value: string | number | null | undefined): number { + if (typeof value === "number" && Number.isFinite(value)) return value; + const parsed = Date.parse(String(value || "")); + return Number.isFinite(parsed) ? parsed : 0; +} + +export function envFlagEnabled(value: string | undefined): boolean { + return ["true", "1", "yes", "on"].includes(normalizeToken(value || "")); +} + +export function evaluateSelfApprovalActor(input: { + approvalActorLogin: string; + prAuthorLogin: string; +}): SelfApprovalActorResult { + const approvalActor = normalizeActorLogin(input.approvalActorLogin); + const prAuthor = normalizeActorLogin(input.prAuthorLogin); + if (!approvalActor) { + return { + allowed: false, + reason: "could not resolve approval actor for self-approval", + }; + } + if (!prAuthor) { + return { + allowed: false, + reason: "could not resolve pull request author for self-approval", + }; + } + if (approvalActor === prAuthor) { + return { + allowed: false, + reason: "approval actor matches the pull request author", + }; + } + return { + allowed: true, + reason: "approval actor is distinct from pull request author", + }; +} + +function normalizeVerdict(value: string): SelfApprovalVerdict | null { + const normalized = normalizeToken(value); + if (normalized === "approve" || normalized === "approved") return "approve"; + if ( + normalized === "request_changes" || + normalized === "changes_requested" || + normalized === "changes_needed" || + normalized === "needs_changes" + ) { + return "request_changes"; + } + if (normalized === "blocked" || normalized === "block") return "blocked"; + return null; +} + +export function evaluateSelfApprovalProvenance(input: { + comments: SelfApprovalSignalComment[]; + trustedActorLogin: string; + expectedHeadSha: string; + allowHumanDecisionGate?: boolean; +}): SelfApprovalProvenanceResult { + const trustedActor = normalizeActorLogin(input.trustedActorLogin); + const expectedHeadSha = String(input.expectedHeadSha || "").trim(); + if (!trustedActor) { + return { + trusted: false, + reason: "could not resolve trusted agent actor for self-approval provenance", + }; + } + if (!expectedHeadSha) { + return { + trusted: false, + reason: "could not resolve expected head SHA for self-approval provenance", + }; + } + + const signals = input.comments + .map((comment, index) => { + const author = normalizeActorLogin(comment.authorLogin); + if (!author || author !== trustedActor) return null; + + const body = String(comment.body || ""); + if (!isReviewSynthesisBody(body)) return null; + + return { + index, + createdAtMs: createdAtMs(comment.createdAt), + conclusion: extractReviewConclusion(body), + recommendedNextStep: extractReviewRecommendedNextStep(body), + reviewedHeadSha: extractReviewSynthesisHeadSha(body), + }; + }) + .filter((signal): signal is { + index: number; + createdAtMs: number; + conclusion: string; + recommendedNextStep: string; + reviewedHeadSha: string; + } => Boolean(signal)) + .sort((left, right) => left.createdAtMs - right.createdAtMs || left.index - right.index); + + const latest = signals[signals.length - 1]; + if (!latest) { + return { + trusted: false, + reason: "missing trusted review synthesis for self-approval", + }; + } + + if (!latest.reviewedHeadSha) { + return { + trusted: false, + reason: "latest trusted review synthesis is missing reviewed head SHA", + }; + } + if (latest.reviewedHeadSha !== expectedHeadSha) { + return { + trusted: false, + reason: "latest trusted review synthesis reviewed a different head SHA", + }; + } + + const conclusion = latest.conclusion || "unknown"; + const recommendedNextStep = normalizeToken(latest.recommendedNextStep || ""); + if (conclusion === "ship") { + return { + trusted: true, + reason: "latest trusted review synthesis verdict is SHIP for current head", + }; + } + if (input.allowHumanDecisionGate && recommendedNextStep === "human_decision") { + return { + trusted: true, + reason: `latest trusted review synthesis recommended HUMAN_DECISION after ${conclusion} for current head`, + }; + } + + return { + trusted: false, + reason: `latest trusted review synthesis verdict is ${conclusion}, not SHIP`, + }; +} + +export function parseSelfApprovalDecision(raw: string): SelfApprovalDecision | null { + const json = extractJsonObject(raw); + if (!json) return null; + + let parsed: unknown; + try { + parsed = JSON.parse(json) as unknown; + } catch { + return null; + } + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null; + + const record = parsed as Record; + const verdict = normalizeVerdict(String(record.verdict || record.decision || "")); + if (!verdict) return null; + + const reason = String(record.reason || record.rationale || "").trim(); + const handoffContext = String(record.handoff_context ?? record.handoffContext ?? "").trim(); + const inspectedHeadSha = String( + record.inspected_head_sha ?? record.inspectedHeadSha ?? record.head_sha ?? record.headSha ?? "", + ).trim(); + + return { + verdict, + reason: reason || "self-approval agent returned no reason", + handoffContext, + inspectedHeadSha, + }; +} + +export function resolveSelfApproval(input: SelfApprovalResolveInput): SelfApprovalResolveResult { + if (!input.allowSelfApprove) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: "AGENT_ALLOW_SELF_APPROVE is not enabled", + handoffContext: "", + }; + } + + if (normalizeToken(input.targetKind) !== "pull_request") { + return { + conclusion: "blocked", + shouldApprove: false, + reason: "self-approval is only supported for pull requests", + handoffContext: "", + }; + } + + if (normalizeToken(input.prState) !== "open") { + return { + conclusion: "blocked", + shouldApprove: false, + reason: `pull request is ${input.prState.toLowerCase() || "not open"}`, + handoffContext: "", + }; + } + + if (!input.decision) { + return { + conclusion: "failed", + shouldApprove: false, + reason: "self-approval agent response was missing a valid JSON decision", + handoffContext: "", + }; + } + + const expectedHeadSha = input.expectedHeadSha.trim(); + const currentHeadSha = input.currentHeadSha.trim(); + const inspectedHeadSha = input.decision.inspectedHeadSha.trim(); + if (!expectedHeadSha || !currentHeadSha || expectedHeadSha !== currentHeadSha) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: "pull request head changed after self-approval inspection", + handoffContext: input.decision.handoffContext, + }; + } + + if (input.decision.verdict === "approve") { + if (!inspectedHeadSha) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: "self-approval approval verdict was missing inspected head SHA", + handoffContext: input.decision.handoffContext, + }; + } + + if (inspectedHeadSha !== expectedHeadSha) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: "self-approval agent reported a different inspected head SHA", + handoffContext: input.decision.handoffContext, + }; + } + + if (input.approvalActorAllowed !== true) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: input.approvalActorReason || "approval actor could not be verified as distinct from pull request author", + handoffContext: input.decision.handoffContext, + }; + } + + if (input.approvalProvenanceTrusted !== true) { + return { + conclusion: "blocked", + shouldApprove: false, + reason: input.approvalProvenanceReason || "missing trusted review synthesis for self-approval", + handoffContext: input.decision.handoffContext, + }; + } + + return { + conclusion: "approved", + shouldApprove: true, + reason: input.decision.reason, + handoffContext: input.decision.handoffContext, + }; + } + + if (input.decision.verdict === "request_changes") { + return { + conclusion: "request_changes", + shouldApprove: false, + reason: input.decision.reason, + handoffContext: input.decision.handoffContext || input.decision.reason, + }; + } + + return { + conclusion: "blocked", + shouldApprove: false, + reason: input.decision.reason, + handoffContext: input.decision.handoffContext, + }; +} + +export function formatSelfApprovalBody(input: { + conclusion: string; + reason: string; + handoffContext?: string; + approved?: boolean; + runUrl?: string; +}): string { + const conclusion = input.conclusion || "unknown"; + const status = input.approved + ? "Approved" + : conclusion === "blocked" + ? "Blocked" + : conclusion === "failed" + ? "Failed" + : conclusion === "request_changes" + ? "Changes requested" + : "Not approved"; + const lines = [ + "Sepo self-approval completed.", + "", + "| Status | Conclusion |", + "|---|---|", + `| ${status} | \`${conclusion}\` |`, + "", + `Reason: ${input.reason || "No reason provided."}`, + ]; + const context = String(input.handoffContext || "").trim(); + if (context && !input.approved) { + lines.push("", "Follow-up context:", context); + } + if (input.runUrl) { + lines.push("", `Run: ${input.runUrl}`); + } + lines.push("", SELF_APPROVAL_STATUS_MARKER); + return lines.join("\n"); +} diff --git a/.agent/src/self-merge.ts b/.agent/src/self-merge.ts new file mode 100644 index 0000000..9f66553 --- /dev/null +++ b/.agent/src/self-merge.ts @@ -0,0 +1,337 @@ +import { type PrReviewRecord, type PrStatusCheckRecord } from "./github.js"; + +export type SelfMergeConclusion = "merged" | "auto_merge_enabled" | "blocked" | "failed"; +export type SelfMergeNextStep = "merge" | "enable_auto_merge" | "none"; + +export const SELF_MERGE_STATUS_MARKER = ""; + +export interface SelfMergeApprovalResult { + approved: boolean; + approvedHeadSha: string; + reason: string; +} + +export interface SelfMergeStatusSummary { + total: number; + pending: number; + failed: number; + pendingNames: string[]; + failedNames: string[]; +} + +export interface SelfMergeResolveInput { + allowSelfMerge: boolean; + targetKind: string; + prState: string; + isDraft: boolean; + currentHeadSha: string; + reviewDecision: string; + mergeStateStatus: string; + mergeable: string; + autoMergeRequestExists?: boolean; + statusChecks: PrStatusCheckRecord[]; + approval: SelfMergeApprovalResult; +} + +export interface SelfMergeResolveResult { + conclusion: SelfMergeConclusion; + nextStep: SelfMergeNextStep; + markReady: boolean; + reason: string; +} + +function normalizeToken(value: string): string { + return String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_"); +} + +function normalizeActorLogin(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/^app\//i, "") + .replace(/\[bot\]$/i, ""); +} + +function createdAtMs(value: string | number | null | undefined): number { + if (typeof value === "number" && Number.isFinite(value)) return value; + const parsed = Date.parse(String(value || "")); + return Number.isFinite(parsed) ? parsed : 0; +} + +function checkName(check: PrStatusCheckRecord, index: number): string { + return String(check.name || "").trim() || `check ${index + 1}`; +} + +export function summarizeStatusChecks(checks: PrStatusCheckRecord[]): SelfMergeStatusSummary { + const failedTokens = new Set([ + "failure", + "failed", + "error", + "cancelled", + "canceled", + "timed_out", + "action_required", + "startup_failure", + ]); + const pendingTokens = new Set([ + "pending", + "queued", + "in_progress", + "waiting", + "requested", + "expected", + ]); + + const pendingNames: string[] = []; + const failedNames: string[] = []; + checks.forEach((check, index) => { + const tokens = [ + normalizeToken(check.conclusion), + normalizeToken(check.state), + normalizeToken(check.status), + ].filter(Boolean); + if (tokens.some((token) => failedTokens.has(token))) { + failedNames.push(checkName(check, index)); + return; + } + if (tokens.some((token) => pendingTokens.has(token))) { + pendingNames.push(checkName(check, index)); + } + }); + + return { + total: checks.length, + pending: pendingNames.length, + failed: failedNames.length, + pendingNames, + failedNames, + }; +} + +export function evaluateSelfMergeApproval(input: { + reviews: PrReviewRecord[]; + trustedActorLogin: string; + currentHeadSha: string; +}): SelfMergeApprovalResult { + const trustedActor = normalizeActorLogin(input.trustedActorLogin); + const currentHeadSha = String(input.currentHeadSha || "").trim(); + if (!trustedActor) { + return { + approved: false, + approvedHeadSha: "", + reason: "could not resolve trusted agent actor for self-merge approval", + }; + } + if (!currentHeadSha) { + return { + approved: false, + approvedHeadSha: "", + reason: "could not resolve pull request head SHA for self-merge approval", + }; + } + + const selfApprovals = input.reviews + .map((review, index) => ({ + index, + state: normalizeToken(review.state), + author: normalizeActorLogin(review.authorLogin), + body: String(review.body || ""), + commitId: String(review.commitId || "").trim(), + submittedAtMs: createdAtMs(review.submittedAt), + })) + .filter((review) => ( + review.state === "approved" && + review.author === trustedActor && + review.body.includes("sepo-agent-self-approval") + )) + .sort((left, right) => left.submittedAtMs - right.submittedAtMs || left.index - right.index); + + const currentHeadApproval = [...selfApprovals].reverse().find((review) => review.commitId === currentHeadSha); + if (currentHeadApproval) { + return { + approved: true, + approvedHeadSha: currentHeadApproval.commitId, + reason: "found current-head self-approval from the authenticated Sepo actor", + }; + } + + const latest = selfApprovals[selfApprovals.length - 1]; + if (latest) { + return { + approved: false, + approvedHeadSha: latest.commitId, + reason: "latest self-approval reviewed a different head SHA", + }; + } + + return { + approved: false, + approvedHeadSha: "", + reason: "missing current-head self-approval from the authenticated Sepo actor", + }; +} + +function formatCheckNames(names: string[]): string { + const shown = names.slice(0, 3).join(", "); + return names.length > 3 ? `${shown}, and ${names.length - 3} more` : shown; +} + +function isCurrentlyMergeable(input: SelfMergeResolveInput): boolean { + const mergeState = normalizeToken(input.mergeStateStatus); + const mergeable = normalizeToken(input.mergeable); + return ( + (mergeState === "clean" || mergeState === "has_hooks") && + (mergeable === "mergeable" || mergeable === "true") + ); +} + +function canEnableAutoMerge(input: SelfMergeResolveInput): boolean { + const mergeState = normalizeToken(input.mergeStateStatus); + const mergeable = normalizeToken(input.mergeable); + if (mergeable === "conflicting" || mergeable === "false") return false; + if (mergeState === "dirty" || mergeState === "draft" || mergeState === "behind") return false; + return ["blocked", "clean", "has_hooks", "unknown", "unstable"].includes(mergeState); +} + +export function resolveSelfMerge(input: SelfMergeResolveInput): SelfMergeResolveResult { + let markReady = false; + + if (!input.allowSelfMerge) { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: "AGENT_ALLOW_SELF_MERGE is not enabled", + }; + } + + if (normalizeToken(input.targetKind) !== "pull_request") { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: "self-merge is only supported for pull requests", + }; + } + + if (normalizeToken(input.prState) !== "open") { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: `pull request is ${String(input.prState || "not open").toLowerCase()}`, + }; + } + + if (input.isDraft) { + markReady = true; + } + + if (!input.currentHeadSha.trim()) { + return { + conclusion: "failed", + nextStep: "none", + markReady: false, + reason: "could not resolve pull request head SHA for self-merge", + }; + } + + if (!input.approval.approved) { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: input.approval.reason || "missing current-head self-approval", + }; + } + + if (normalizeToken(input.reviewDecision) === "changes_requested") { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: "pull request has blocking requested changes", + }; + } + + const checks = summarizeStatusChecks(input.statusChecks); + if (checks.failed > 0) { + return { + conclusion: "blocked", + nextStep: "none", + markReady: false, + reason: `status checks are failing: ${formatCheckNames(checks.failedNames)}`, + }; + } + + if (checks.pending > 0) { + const autoMergeEligible = canEnableAutoMerge(input); + if (input.autoMergeRequestExists && autoMergeEligible) { + return { + conclusion: "auto_merge_enabled", + nextStep: "none", + markReady, + reason: "GitHub auto-merge is already enabled while checks are pending", + }; + } + if (autoMergeEligible) { + return { + conclusion: "auto_merge_enabled", + nextStep: "enable_auto_merge", + markReady, + reason: `status checks are pending: ${formatCheckNames(checks.pendingNames)}; enabling GitHub auto-merge`, + }; + } + return { + conclusion: "blocked", + nextStep: "none", + markReady, + reason: `pull request is not eligible for auto-merge while checks are pending (merge state: ${input.mergeStateStatus || "unknown"})`, + }; + } + + if (isCurrentlyMergeable(input)) { + return { + conclusion: "merged", + nextStep: "merge", + markReady, + reason: "pull request is approved, current, and mergeable", + }; + } + + return { + conclusion: "blocked", + nextStep: "none", + markReady, + reason: `pull request is not currently mergeable (merge state: ${input.mergeStateStatus || "unknown"})`, + }; +} + +export function formatSelfMergeBody(input: { + conclusion: SelfMergeConclusion | string; + reason: string; + runUrl?: string; +}): string { + const conclusion = input.conclusion || "unknown"; + const status = conclusion === "merged" + ? "Merged" + : conclusion === "auto_merge_enabled" + ? "Auto-merge enabled" + : conclusion === "failed" + ? "Failed" + : "Blocked"; + const lines = [ + "Sepo self-merge completed.", + "", + "| Status | Conclusion |", + "|---|---|", + `| ${status} | \`${conclusion}\` |`, + "", + `Reason: ${input.reason || "No reason provided."}`, + ]; + if (input.runUrl) { + lines.push("", `Run: ${input.runUrl}`); + } + lines.push("", SELF_MERGE_STATUS_MARKER); + return lines.join("\n"); +} diff --git a/.agent/src/session-bundle.ts b/.agent/src/session-bundle.ts new file mode 100644 index 0000000..726aa0e --- /dev/null +++ b/.agent/src/session-bundle.ts @@ -0,0 +1,404 @@ +import { execFileSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { + cpSync, + existsSync, + mkdtempSync, + mkdirSync, + readFileSync, + rmSync, + statSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; + +import type { SessionPolicy } from "./session-policy.js"; +import { attemptsResume } from "./session-policy.js"; + +export const SESSION_BUNDLE_SCHEMA_VERSION = 1; +export const RESTORABLE_SESSION_BUNDLE_BACKEND = "github-artifact"; +export const DEBUG_SESSION_BUNDLE_BACKEND = "github-artifact-debug"; + +export type SessionBundleMode = "auto" | "always" | "never"; +export type SessionBundleRestoreStatus = + | "not_applicable" + | "not_available" + | "restored" + | "failed"; + +export interface SessionBundleManifestFile { + relative_path: string; + size_bytes: number; + sha256: string; +} + +export interface SessionBundleManifest { + schema_version: number; + agent: string; + thread_key: string; + repo_slug: string; + cwd: string; + acpx_record_id: string; + acpx_session_id: string; + created_at: string; + files: SessionBundleManifestFile[]; +} + +export interface SessionBundleFile extends SessionBundleManifestFile { + absolute_path: string; +} + +export interface CreatedSessionBundle { + bundlePath: string; + manifest: SessionBundleManifest; + totalSizeBytes: number; + fileCount: number; +} + +function sha256File(path: string): string { + const hash = createHash("sha256"); + hash.update(readFileSync(path)); + return hash.digest("hex"); +} + +function shortHash(value: string): string { + return createHash("sha256").update(value).digest("hex").slice(0, 12); +} + +function sanitizeArtifactComponent(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/[^a-z0-9._-]+/g, "-") + .replace(/^-+|-+$/g, "") + .slice(0, 40) || "default"; +} + +function escapeFindNamePattern(value: string): string { + return value.replace(/([*?\[\]\\])/g, "\\$1"); +} + +function findFilesByName(root: string, pattern: string): string[] { + if (!root || !existsSync(root)) { + return []; + } + + try { + const output = execFileSync("find", [root, "-type", "f", "-name", pattern], { + stdio: ["pipe", "pipe", "pipe"], + maxBuffer: 10 * 1024 * 1024, + }).toString("utf8"); + return output + .split("\n") + .map((line) => line.trim()) + .filter(Boolean) + .sort(); + } catch { + return []; + } +} + +function toHomeRelativePath(absolutePath: string, homeDir: string): string | null { + const resolvedHome = resolve(homeDir); + const resolvedPath = resolve(absolutePath); + const rel = relative(resolvedHome, resolvedPath); + if (!rel || rel.startsWith("..") || isAbsolute(rel)) { + return null; + } + return rel.replace(/\\/g, "/"); +} + +function addBundleFile( + files: Map, + absolutePath: string, + homeDir: string, +): void { + if (!existsSync(absolutePath)) { + return; + } + + const relativePath = toHomeRelativePath(absolutePath, homeDir); + if (!relativePath || files.has(relativePath)) { + return; + } + + const stats = statSync(absolutePath); + if (!stats.isFile()) { + return; + } + + files.set(relativePath, { + absolute_path: absolutePath, + relative_path: relativePath, + size_bytes: stats.size, + sha256: sha256File(absolutePath), + }); +} + +export function parseSessionBundleMode(value: string | undefined): SessionBundleMode { + const normalized = value?.trim().toLowerCase(); + if (normalized === "always" || normalized === "never") { + return normalized; + } + return "auto"; +} + +export function shouldRestoreSessionBundles( + mode: SessionBundleMode, + policy: SessionPolicy, +): boolean { + if (policy === "none" || mode === "never") { + return false; + } + return attemptsResume(policy); +} + +export function shouldBackupSessionBundles( + mode: SessionBundleMode, + policy: SessionPolicy, +): boolean { + if (policy === "none" || mode === "never") { + return false; + } + if (mode === "always") { + return true; + } + return attemptsResume(policy); +} + +export function isRestorableSessionBundleBackend(backend: string): boolean { + return backend === "" || backend === RESTORABLE_SESSION_BUNDLE_BACKEND; +} + +export function hasValidThreadTargetNumber(targetKind: string, targetNumber: number): boolean { + if (!Number.isFinite(targetNumber)) { + return false; + } + if (targetKind === "repository") { + return targetNumber >= 0; + } + return targetNumber > 0; +} + +export function buildSessionBundleArtifactName( + threadKey: string, + runId: string, +): string { + const [, targetKind = "target", targetNumber = "0", route = "route", lane = "default"] = + String(threadKey || "").split(":"); + const suffix = shortHash(threadKey); + const parts = [ + "session-bundle", + sanitizeArtifactComponent(targetKind), + sanitizeArtifactComponent(targetNumber), + sanitizeArtifactComponent(route), + sanitizeArtifactComponent(lane), + suffix, + sanitizeArtifactComponent(runId || "run"), + ]; + return parts.join("-"); +} + +export function formatSessionRestoreNotice(args: { + resumeStatus?: string; + runStatus?: string; +}): string { + const resumeStatus = String(args.resumeStatus || "").trim().toLowerCase(); + const runStatus = String(args.runStatus || "").trim().toLowerCase(); + + if (resumeStatus === "fallback_fresh") { + if (runStatus === "success" || runStatus === "no_changes" || runStatus === "verify_failed") { + return "Session continuity could not be restored, so this run continued with a fresh session."; + } + return "Session continuity could not be restored for this run."; + } + + if (resumeStatus === "failed") { + return "Session continuity could not be restored for this run."; + } + + return ""; +} + +export function discoverSessionBundleFiles(args: { + agent: string; + acpxRecordId: string; + acpxSessionId: string; + homeDir: string; +}): SessionBundleFile[] { + const files = new Map(); + const normalizedAgent = String(args.agent || "").trim().toLowerCase(); + const homeDir = resolve(args.homeDir); + + if (args.acpxRecordId) { + addBundleFile( + files, + join(homeDir, ".acpx", "sessions", `${args.acpxRecordId}.json`), + homeDir, + ); + addBundleFile( + files, + join(homeDir, ".acpx", "sessions", `${args.acpxRecordId}.stream.ndjson`), + homeDir, + ); + } + + if (args.acpxSessionId) { + if (normalizedAgent === "codex") { + for (const match of findFilesByName( + join(homeDir, ".codex", "sessions"), + `*${escapeFindNamePattern(args.acpxSessionId)}*.jsonl`, + )) { + addBundleFile(files, match, homeDir); + } + } + + if (normalizedAgent === "claude") { + for (const match of findFilesByName( + join(homeDir, ".claude", "projects"), + `*${escapeFindNamePattern(args.acpxSessionId)}*.jsonl`, + )) { + addBundleFile(files, match, homeDir); + } + } + } + + return Array.from(files.values()).sort((a, b) => + a.relative_path.localeCompare(b.relative_path), + ); +} + +export function createSessionBundle(args: { + agent: string; + threadKey: string; + repoSlug: string; + cwd: string; + acpxRecordId: string; + acpxSessionId: string; + homeDir: string; + runnerTemp?: string; +}): CreatedSessionBundle | null { + const files = discoverSessionBundleFiles({ + agent: args.agent, + acpxRecordId: args.acpxRecordId, + acpxSessionId: args.acpxSessionId, + homeDir: args.homeDir, + }); + + if (files.length === 0) { + return null; + } + + const stageDir = mkdtempSync(join(args.runnerTemp || tmpdir(), "session-bundle-stage-")); + const payloadDir = join(stageDir, "files"); + mkdirSync(payloadDir, { recursive: true }); + + const manifest: SessionBundleManifest = { + schema_version: SESSION_BUNDLE_SCHEMA_VERSION, + agent: args.agent, + thread_key: args.threadKey, + repo_slug: args.repoSlug, + cwd: args.cwd, + acpx_record_id: args.acpxRecordId, + acpx_session_id: args.acpxSessionId, + created_at: new Date().toISOString(), + files: files.map((file) => ({ + relative_path: file.relative_path, + size_bytes: file.size_bytes, + sha256: file.sha256, + })), + }; + + for (const file of files) { + const target = join(payloadDir, file.relative_path); + mkdirSync(dirname(target), { recursive: true }); + cpSync(file.absolute_path, target); + } + + writeFileSync(join(stageDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8"); + + const bundlePath = join( + args.runnerTemp || tmpdir(), + `session-bundle-${shortHash(args.threadKey + args.acpxSessionId)}.tgz`, + ); + + execFileSync("tar", ["-czf", bundlePath, "-C", stageDir, "manifest.json", "files"], { + stdio: ["pipe", "pipe", "pipe"], + }); + rmSync(stageDir, { recursive: true, force: true }); + + return { + bundlePath, + manifest, + totalSizeBytes: files.reduce((sum, file) => sum + file.size_bytes, 0), + fileCount: files.length, + }; +} + +function validateManifest(value: unknown): SessionBundleManifest { + if (!value || typeof value !== "object") { + throw new Error("Session bundle manifest must be an object"); + } + + const manifest = value as SessionBundleManifest; + if (manifest.schema_version !== SESSION_BUNDLE_SCHEMA_VERSION) { + throw new Error( + `Unsupported session bundle schema: ${String((manifest as { schema_version?: unknown }).schema_version ?? "missing")}`, + ); + } + if (!Array.isArray(manifest.files)) { + throw new Error("Session bundle manifest is missing files"); + } + return manifest; +} + +export function restoreSessionBundle(bundlePath: string, homeDir: string): SessionBundleManifest { + const extractDir = mkdtempSync(join(tmpdir(), "session-bundle-restore-")); + const resolvedHome = resolve(homeDir); + const homePrefix = resolvedHome.endsWith(sep) ? resolvedHome : resolvedHome + sep; + + try { + execFileSync("tar", ["-xzf", bundlePath, "-C", extractDir], { + stdio: ["pipe", "pipe", "pipe"], + }); + + const manifest = validateManifest( + JSON.parse(readFileSync(join(extractDir, "manifest.json"), "utf8")), + ); + + for (const file of manifest.files) { + const rel = String(file.relative_path || "").replace(/\\/g, "/"); + if (!rel || isAbsolute(rel) || rel.startsWith("../") || rel.includes("/../")) { + throw new Error(`Invalid bundle path: ${rel || "missing"}`); + } + + const source = join(extractDir, "files", rel); + if (!existsSync(source)) { + throw new Error(`Bundle file missing: ${rel}`); + } + + const actualSha = sha256File(source); + if (actualSha !== file.sha256) { + throw new Error(`Bundle file checksum mismatch: ${rel}`); + } + + const dest = resolve(resolvedHome, rel); + if (!(dest === resolvedHome || dest.startsWith(homePrefix))) { + throw new Error(`Bundle path escapes HOME: ${rel}`); + } + + mkdirSync(dirname(dest), { recursive: true }); + cpSync(source, dest); + } + + return manifest; + } finally { + rmSync(extractDir, { recursive: true, force: true }); + } +} + +export function findSessionBundleArchive(dir: string): string | null { + const matches = findFilesByName(dir, "*.tgz"); + return matches[0] || null; +} diff --git a/.agent/src/session-policy.ts b/.agent/src/session-policy.ts new file mode 100644 index 0000000..b5d2876 --- /dev/null +++ b/.agent/src/session-policy.ts @@ -0,0 +1,46 @@ +// Session continuity policy. +// +// Separates three concerns: +// 1. whether a route tracks durable thread state +// 2. whether it attempts to resume prior ACP sessions across runs +// 3. whether continuity failures are fatal or best-effort +// +// Policy is explicit in workflow YAML. We intentionally do not provide +// route-based defaults or backward-compatibility fallbacks. + +export type SessionPolicy = + | "none" + | "track-only" + | "resume-best-effort" + | "resume-required"; + +export type SessionMode = "exec" | "persistent"; + +export function parseSessionPolicy(value: string | undefined): SessionPolicy | null { + const normalized = value?.trim().toLowerCase(); + if ( + normalized === "none" || + normalized === "track-only" || + normalized === "resume-best-effort" || + normalized === "resume-required" + ) { + return normalized; + } + return null; +} + +export function sessionModeForPolicy(policy: SessionPolicy): SessionMode { + return attemptsResume(policy) ? "persistent" : "exec"; +} + +export function tracksThreadState(policy: SessionPolicy): boolean { + return policy !== "none"; +} + +export function attemptsResume(policy: SessionPolicy): boolean { + return policy === "resume-best-effort" || policy === "resume-required"; +} + +export function requiresResumeContinuity(policy: SessionPolicy): boolean { + return policy === "resume-required"; +} diff --git a/.agent/src/sub-orchestration.ts b/.agent/src/sub-orchestration.ts new file mode 100644 index 0000000..f86d4eb --- /dev/null +++ b/.agent/src/sub-orchestration.ts @@ -0,0 +1,221 @@ +export type SubOrchestratorState = "running" | "done" | "blocked" | "failed"; + +export interface SubOrchestratorMarker { + parent: number; + stage: string; + state: SubOrchestratorState; + parentRound?: number; +} + +export interface SubOrchestratorChildLink { + parent: number; + stage: string; + child: number; +} + +const MARKER_PREFIX = "sepo-sub-orchestrator"; +const MARKER_RE = //i; +const CHILD_LINK_MARKER_PREFIX = "sepo-sub-orchestrator-child"; +const CHILD_LINK_MARKER_RE = //i; +const VALID_STATES = new Set(["running", "done", "blocked", "failed"]); + +export function normalizeSubOrchestratorStage(value: string): string { + return String(value || "") + .trim() + .toLowerCase() + .replace(/[^a-z0-9._-]+/g, "-") + .replace(/^-+|-+$/g, "") + .slice(0, 60) || "stage"; +} + +function parseMarkerTokens(text: string): Map { + const tokens = new Map(); + for (const match of String(text || "").matchAll(/\b([a-z_]+):([^\s]+)/gi)) { + tokens.set(match[1].toLowerCase(), match[2]); + } + return tokens; +} + +function parsePositiveInteger(value: string | undefined): number { + const text = String(value || "").trim(); + if (!/^\d+$/.test(text)) return 0; + const parsed = Number.parseInt(text, 10); + return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 0; +} + +export function formatSubOrchestratorMarker(input: { + parent: number; + stage: string; + state?: SubOrchestratorState; + parentRound?: number; +}): string { + const parts = [ + MARKER_PREFIX, + `parent:${input.parent}`, + `stage:${normalizeSubOrchestratorStage(input.stage)}`, + `state:${input.state || "running"}`, + ]; + const parentRound = parsePositiveInteger(String(input.parentRound || "")); + if (parentRound) parts.push(`parent_round:${parentRound}`); + return ``; +} + +export function parseSubOrchestratorMarker(body: string): SubOrchestratorMarker | null { + const match = String(body || "").match(MARKER_RE); + if (!match) return null; + + const tokens = parseMarkerTokens(match[1] || ""); + const parent = parsePositiveInteger(tokens.get("parent")); + const stageToken = tokens.get("stage"); + const stage = stageToken ? normalizeSubOrchestratorStage(stageToken) : ""; + const rawState = String(tokens.get("state") || "").toLowerCase() as SubOrchestratorState; + if (!parent || !stage || !VALID_STATES.has(rawState)) return null; + + const parentRound = parsePositiveInteger(tokens.get("parent_round")); + return { + parent, + stage, + state: rawState, + ...(parentRound ? { parentRound } : {}), + }; +} + +export function formatSubOrchestratorChildLinkMarker(input: { + parent: number; + stage: string; + child: number; +}): string { + return ``; +} + +export function parseSubOrchestratorChildLinkMarker(body: string): SubOrchestratorChildLink | null { + const match = String(body || "").match(CHILD_LINK_MARKER_RE); + if (!match) return null; + + const tokens = parseMarkerTokens(match[1] || ""); + const parent = parsePositiveInteger(tokens.get("parent")); + const stageToken = tokens.get("stage"); + const stage = stageToken ? normalizeSubOrchestratorStage(stageToken) : ""; + const child = parsePositiveInteger(tokens.get("child")); + if (!parent || !stage || !child) return null; + + return { parent, stage, child }; +} + +export function updateSubOrchestratorMarkerState(body: string, state: SubOrchestratorState): string { + const marker = parseSubOrchestratorMarker(body); + if (!marker) return body; + return String(body || "").replace(MARKER_RE, formatSubOrchestratorMarker({ ...marker, state })); +} + +export function updateSubOrchestratorMarkerParentRound(body: string, parentRound: number): string { + const marker = parseSubOrchestratorMarker(body); + if (!marker) return body; + return String(body || "").replace(MARKER_RE, formatSubOrchestratorMarker({ ...marker, parentRound })); +} + +export function formatSubOrchestrationIssueBody(input: { + parentIssue: number; + stage: string; + taskInstructions: string; + baseBranch?: string; + basePr?: string; + parentRound?: number; +}): string { + const lines = [ + `Parent issue: #${input.parentIssue}`, + "", + `Stage: ${input.stage.trim() || "Sub-orchestration"}`, + "", + "## Task", + "", + input.taskInstructions.trim() || "Continue the parent orchestration subtask.", + ]; + + if (input.baseBranch || input.basePr) { + lines.push("", "## Base", ""); + if (input.baseBranch) lines.push(`- base_branch: ${input.baseBranch}`); + if (input.basePr) lines.push(`- base_pr: #${input.basePr}`); + } + + lines.push("", formatSubOrchestratorMarker({ + parent: input.parentIssue, + stage: input.stage, + parentRound: input.parentRound, + })); + return lines.join("\n"); +} + +function normalizeRepoSlug(value: string): string { + return String(value || "").trim().toLowerCase(); +} + +export function extractClosingIssueNumber(text: string, currentRepo = ""): number | null { + const currentRepoSlug = normalizeRepoSlug(currentRepo); + const closingRefRe = + /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|implement(?:s|ed)?)\s+(?:(?[\w.-]+\/[\w.-]+)#|#)(?\d+)\b/gi; + + for (const match of String(text || "").matchAll(closingRefRe)) { + const referencedRepo = normalizeRepoSlug(match.groups?.repo || ""); + if (referencedRepo && referencedRepo !== currentRepoSlug) { + continue; + } + if (referencedRepo && !currentRepoSlug) { + continue; + } + const parsed = Number.parseInt(match.groups?.number || "", 10); + if (Number.isFinite(parsed) && parsed > 0) return parsed; + } + return null; +} + +function isAuthorizationStopReason(reason: string): boolean { + return reason.startsWith("orchestrate requests require ") || + /\brequests currently require\b/.test(reason); +} + +function isRoundLimitStopReason(reason: string): boolean { + return reason === "automation round budget exhausted" || + reason.includes("round budget exhausted") || + reason.includes("round limit") || + reason.includes("max rounds") || + reason.includes("maximum rounds"); +} + +const SELF_APPROVAL_TERMINAL_STATES: Record = { + approved: "done", + blocked: "blocked", + failed: "failed", +}; + +const SELF_MERGE_TERMINAL_STATES: Record = { + auto_merge_enabled: "done", + blocked: "blocked", + failed: "failed", + merged: "done", +}; + +export function resultStateFromTerminal(input: { + sourceAction: string; + sourceConclusion: string; + reason: string; +}): SubOrchestratorState { + const action = input.sourceAction.trim().toLowerCase().replace(/[\s-]+/g, "_"); + const conclusion = input.sourceConclusion.trim().toLowerCase().replace(/[\s-]+/g, "_"); + const reason = input.reason.trim().toLowerCase(); + if (action === "review" && conclusion === "ship") return "done"; + if (action === "agent_self_approve" && SELF_APPROVAL_TERMINAL_STATES[conclusion]) { + return SELF_APPROVAL_TERMINAL_STATES[conclusion]; + } + if (action === "agent_self_merge" && SELF_MERGE_TERMINAL_STATES[conclusion]) { + return SELF_MERGE_TERMINAL_STATES[conclusion]; + } + if ( + reason.startsWith("agent planner blocked:") || + isAuthorizationStopReason(reason) || + isRoundLimitStopReason(reason) + ) { + return "blocked"; + } + return "failed"; +} diff --git a/.agent/src/task-timeout-policy.ts b/.agent/src/task-timeout-policy.ts new file mode 100644 index 0000000..cf8ff5d --- /dev/null +++ b/.agent/src/task-timeout-policy.ts @@ -0,0 +1,87 @@ +// Parses AGENT_TASK_TIMEOUT_POLICY, the repository-level configuration for +// outer GitHub Actions step timeouts on agent tasks. +// +// Shape (both sections optional): +// { +// "default_minutes": 30, +// "route_overrides": { +// "": 60, +// ... +// } +// } +// +// Default when empty or unset: every route gets 30 minutes. + +export const DEFAULT_TASK_TIMEOUT_MINUTES = 30; +export const MAX_TASK_TIMEOUT_MINUTES = 360; + +const VALID_ROUTE_KEY = /^[a-z0-9][a-z0-9._-]*$/; + +export interface TaskTimeoutPolicy { + defaultMinutes: number; + routeOverrides: Record; +} + +function normalizeMinutes(value: unknown, label: string): number { + if (!Number.isInteger(value) || Number(value) <= 0) { + throw new Error(`${label} must be a positive integer`); + } + const minutes = Number(value); + if (minutes > MAX_TASK_TIMEOUT_MINUTES) { + throw new Error(`${label} must be at most ${MAX_TASK_TIMEOUT_MINUTES}`); + } + return minutes; +} + +export function parseTaskTimeoutPolicy(raw: string): TaskTimeoutPolicy { + const text = String(raw || "").trim(); + if (!text) { + return { defaultMinutes: DEFAULT_TASK_TIMEOUT_MINUTES, routeOverrides: {} }; + } + + const payload = JSON.parse(text) as Record; + if (!payload || typeof payload !== "object" || Array.isArray(payload)) { + throw new Error("Task timeout policy must be a JSON object"); + } + + const policy: TaskTimeoutPolicy = { + defaultMinutes: DEFAULT_TASK_TIMEOUT_MINUTES, + routeOverrides: {}, + }; + + if ("default_minutes" in payload) { + policy.defaultMinutes = normalizeMinutes(payload.default_minutes, "default_minutes"); + } + + if ("route_overrides" in payload) { + const overrides = payload.route_overrides; + if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) { + throw new Error("route_overrides must be an object"); + } + for (const [route, minutes] of Object.entries(overrides)) { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (!VALID_ROUTE_KEY.test(normalizedRoute)) { + throw new Error( + `Invalid route override key in task timeout policy: ${normalizedRoute || "missing"}`, + ); + } + policy.routeOverrides[normalizedRoute] = normalizeMinutes( + minutes, + `route_overrides.${normalizedRoute}`, + ); + } + } + + return policy; +} + +export function getTaskTimeoutMinutesForRoute( + policy: TaskTimeoutPolicy, + route: string, +): number { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if (normalizedRoute && normalizedRoute in policy.routeOverrides) { + return policy.routeOverrides[normalizedRoute]!; + } + return policy.defaultMinutes; +} diff --git a/.agent/src/thread-state.ts b/.agent/src/thread-state.ts new file mode 100644 index 0000000..f5dde47 --- /dev/null +++ b/.agent/src/thread-state.ts @@ -0,0 +1,507 @@ +// Thread state: durable cross-run state for agent sessions. +// +// Pure data operations (types, create, update, normalize) at the top. +// Git-refs I/O at the bottom — stores state as JSON blobs in orphan +// commits under refs/agent-state/. O(1) reads, atomic +// writes via --force-with-lease, built-in audit trail, no comment +// pollution, works for all target kinds (issues, PRs, discussions). +// +// Ref layout: +// refs/agent-state/ → commit → tree → state.json (blob) + +import { git, buildAuthUrl } from "./git.js"; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export const THREAD_STATE_SCHEMA_VERSION = 3; + +export type ThreadStatus = "pending" | "running" | "completed" | "failed"; +export type ThreadResumeStatus = "not_attempted" | "resumed" | "fallback_fresh" | "failed"; +export type ThreadBundleRestoreStatus = + | "not_attempted" + | "not_available" + | "restored" + | "restored_from_fork" + | "failed"; + +export interface ThreadState { + schema_version: number; + thread_key: string; + acpxRecordId: string; + acpxSessionId: string; + agentSessionId: string; + branch: string; + status: ThreadStatus; + resume_status: ThreadResumeStatus; + last_resume_error: string; + resumed_from_session_id: string; + session_bundle_backend: string; + session_bundle_artifact_id: string; + session_bundle_artifact_name: string; + // Workflow run that uploaded the artifact; needed for `gh run download`. + session_bundle_run_id: string; + bundle_restore_status: ThreadBundleRestoreStatus; + last_bundle_restore_error: string; + forked_from_thread_key: string; + forked_from_acpx_session_id: string; + last_run_url: string; + last_comment_url: string; + attempt_count: number; + created_at: string; + updated_at: string; +} + +interface ThreadStateRecord extends Record { + schema_version?: unknown; + thread_key?: unknown; + acpxRecordId?: unknown; + acpxSessionId?: unknown; + agentSessionId?: unknown; + branch?: unknown; + status?: unknown; + resume_status?: unknown; + last_resume_error?: unknown; + resumed_from_session_id?: unknown; + session_bundle_backend?: unknown; + session_bundle_artifact_id?: unknown; + session_bundle_artifact_name?: unknown; + session_bundle_run_id?: unknown; + bundle_restore_status?: unknown; + last_bundle_restore_error?: unknown; + forked_from_thread_key?: unknown; + forked_from_acpx_session_id?: unknown; + last_run_url?: unknown; + last_comment_url?: unknown; + attempt_count?: unknown; + created_at?: unknown; + updated_at?: unknown; +} + +const VALID_THREAD_STATUSES = new Set([ + "pending", + "running", + "completed", + "failed", +]); +const VALID_RESUME_STATUSES = new Set([ + "not_attempted", + "resumed", + "fallback_fresh", + "failed", +]); +const VALID_BUNDLE_RESTORE_STATUSES = new Set([ + "not_attempted", + "not_available", + "restored", + "restored_from_fork", + "failed", +]); + +// --------------------------------------------------------------------------- +// Pure data operations +// --------------------------------------------------------------------------- + +export function createThreadState(threadKey: string): ThreadState { + const now = new Date().toISOString(); + return { + schema_version: THREAD_STATE_SCHEMA_VERSION, + thread_key: threadKey, + acpxRecordId: "", + acpxSessionId: "", + agentSessionId: "", + branch: "", + status: "pending", + resume_status: "not_attempted", + last_resume_error: "", + resumed_from_session_id: "", + session_bundle_backend: "", + session_bundle_artifact_id: "", + session_bundle_artifact_name: "", + session_bundle_run_id: "", + bundle_restore_status: "not_attempted", + last_bundle_restore_error: "", + forked_from_thread_key: "", + forked_from_acpx_session_id: "", + last_run_url: "", + last_comment_url: "", + attempt_count: 0, + created_at: now, + updated_at: now, + }; +} + +export function updateThreadState( + state: ThreadState, + updates: Partial, +): ThreadState { + return { + ...state, + ...updates, + schema_version: state.schema_version, + thread_key: state.thread_key, + created_at: state.created_at, + updated_at: new Date().toISOString(), + }; +} + +function toStringOrEmpty(value: unknown): string { + return typeof value === "string" ? value : ""; +} + +function toIsoOrNow(value: unknown, fallback: string): string { + return typeof value === "string" && value ? value : fallback; +} + +function toPositiveIntOrZero(value: unknown): number { + const n = Number(value); + return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0; +} + +/** + * Normalizes persisted thread state, including legacy pre-schema-v3 data. + * Legacy `status: "resume_failed"` is upgraded to: + * - `status: "failed"` + * - `resume_status: "failed"` + */ +export function normalizeThreadState( + raw: unknown, + fallbackThreadKey?: string, +): ThreadState | null { + if (!raw || typeof raw !== "object") { + return null; + } + + const record = raw as ThreadStateRecord; + const now = new Date().toISOString(); + const threadKey = + (typeof record.thread_key === "string" && record.thread_key) || + fallbackThreadKey || + ""; + if (!threadKey) { + return null; + } + + const rawStatus = typeof record.status === "string" ? record.status : "pending"; + const status: ThreadStatus = VALID_THREAD_STATUSES.has(rawStatus as ThreadStatus) + ? (rawStatus as ThreadStatus) + : rawStatus === "resume_failed" + ? "failed" + : "pending"; + + const resumeStatus: ThreadResumeStatus = VALID_RESUME_STATUSES.has(record.resume_status as ThreadResumeStatus) + ? (record.resume_status as ThreadResumeStatus) + : rawStatus === "resume_failed" + ? "failed" + : "not_attempted"; + + const bundleRestoreStatus: ThreadBundleRestoreStatus = VALID_BUNDLE_RESTORE_STATUSES.has( + record.bundle_restore_status as ThreadBundleRestoreStatus, + ) + ? (record.bundle_restore_status as ThreadBundleRestoreStatus) + : "not_attempted"; + + return { + schema_version: THREAD_STATE_SCHEMA_VERSION, + thread_key: threadKey, + acpxRecordId: toStringOrEmpty(record.acpxRecordId), + acpxSessionId: toStringOrEmpty(record.acpxSessionId), + agentSessionId: toStringOrEmpty(record.agentSessionId), + branch: toStringOrEmpty(record.branch), + status, + resume_status: resumeStatus, + last_resume_error: toStringOrEmpty(record.last_resume_error), + resumed_from_session_id: toStringOrEmpty(record.resumed_from_session_id), + session_bundle_backend: toStringOrEmpty(record.session_bundle_backend), + session_bundle_artifact_id: toStringOrEmpty(record.session_bundle_artifact_id), + session_bundle_artifact_name: toStringOrEmpty(record.session_bundle_artifact_name), + session_bundle_run_id: toStringOrEmpty(record.session_bundle_run_id), + bundle_restore_status: bundleRestoreStatus, + last_bundle_restore_error: toStringOrEmpty(record.last_bundle_restore_error), + forked_from_thread_key: toStringOrEmpty(record.forked_from_thread_key), + forked_from_acpx_session_id: toStringOrEmpty(record.forked_from_acpx_session_id), + last_run_url: toStringOrEmpty(record.last_run_url), + last_comment_url: toStringOrEmpty(record.last_comment_url), + attempt_count: toPositiveIntOrZero(record.attempt_count), + created_at: toIsoOrNow(record.created_at, now), + updated_at: toIsoOrNow(record.updated_at, now), + }; +} + +// --------------------------------------------------------------------------- +// Ref naming +// --------------------------------------------------------------------------- + +const REF_PREFIX = "refs/agent-state"; +const STATE_FILENAME = "state.json"; + +/** + * Converts a thread_key into a safe, injective ref path component. + * thread_key format: owner/repo:target_kind:target_number:route:lane + * + * Uses percent-encoding for `/` and `%` to guarantee the mapping is + * reversible — distinct thread keys always produce distinct ref names. + * `:` is replaced with `--` (safe since `--` cannot appear in any + * individual field value). + */ +export function threadKeyToRefName(threadKey: string): string { + return threadKey + .replace(/%/g, "%25") + .replace(/\//g, "%2F") + .replace(/:/g, "--") + .replace(/[^a-zA-Z0-9._%-]/g, "_"); +} + +export function refPathForThreadKey(threadKey: string): string { + return `${REF_PREFIX}/${threadKeyToRefName(threadKey)}`; +} + +// --------------------------------------------------------------------------- +// Read +// --------------------------------------------------------------------------- + +const REF_NOT_FOUND_PATTERN = /couldn't find remote ref|no matching remote head/i; + +export function fetchThreadState( + threadKey: string, + cwd: string, + opts?: PushOptions, +): ThreadState | null { + const ref = refPathForThreadKey(threadKey); + const origin = opts?.remote ?? "origin"; + const fetchTarget = resolveRemoteTarget(origin, opts); + + try { + git(["fetch", "--no-tags", fetchTarget, `+${ref}:${ref}`], cwd); + } catch (err: unknown) { + const stderr = (err as { stderr?: Buffer })?.stderr?.toString("utf8") ?? String(err); + if (REF_NOT_FOUND_PATTERN.test(stderr)) { + return null; + } + throw err; + } + + try { + const json = git(["cat-file", "blob", `${ref}:${STATE_FILENAME}`], cwd); + return normalizeThreadState(JSON.parse(json), threadKey); + } catch { + return null; + } +} + +// --------------------------------------------------------------------------- +// Write +// --------------------------------------------------------------------------- + +export interface PushOptions { + remote?: string; + token?: string; + repo?: string; +} + +function resolveRemoteTarget(remote: string, opts?: PushOptions): string { + if (opts?.token && opts?.repo) { + return buildAuthUrl(opts.token, opts.repo); + } + return remote; +} + +export function writeThreadState( + threadKey: string, + state: ThreadState, + cwd: string, + opts?: PushOptions, +): void { + const ref = refPathForThreadKey(threadKey); + const origin = opts?.remote ?? "origin"; + const json = JSON.stringify(state, null, 2) + "\n"; + + const blobSha = git(["hash-object", "-w", "--stdin"], cwd, json); + const treeInput = `100644 blob ${blobSha}\t${STATE_FILENAME}\n`; + const treeSha = git(["mktree"], cwd, treeInput); + + let parentArg: string[]; + let expectedOid: string | null = null; + try { + const parentSha = git(["rev-parse", "--verify", ref], cwd); + parentArg = ["-p", parentSha]; + expectedOid = parentSha; + } catch { + parentArg = []; + } + + const commitMessage = `agent-state: ${state.status}/${state.resume_status} (attempt ${state.attempt_count})`; + const commitSha = git(["commit-tree", treeSha, ...parentArg, "-m", commitMessage], cwd); + + git(["update-ref", ref, commitSha], cwd); + + const pushTarget = resolveRemoteTarget(origin, opts); + const leaseArg = expectedOid + ? `--force-with-lease=${ref}:${expectedOid}` + : "--force"; + git(["push", leaseArg, pushTarget, `${ref}:${ref}`], cwd); +} + +// --------------------------------------------------------------------------- +// High-level operations +// --------------------------------------------------------------------------- + +export function getThreadState( + threadKey: string, + cwd: string, + opts?: PushOptions, +): ThreadState | null { + return fetchThreadState(threadKey, cwd, opts); +} + +export interface ThreadStateRunningUpdates { + last_run_url?: string; + branch?: string; + resume_status?: ThreadResumeStatus; + last_resume_error?: string; + resumed_from_session_id?: string; + forked_from_thread_key?: string; + forked_from_acpx_session_id?: string; + bundle_restore_status?: ThreadBundleRestoreStatus; + last_bundle_restore_error?: string; +} + +export function markThreadRunning( + threadKey: string, + cwd: string, + updates: ThreadStateRunningUpdates, + opts?: PushOptions, +): ThreadState { + const existing = fetchThreadState(threadKey, cwd, opts); + + let state: ThreadState; + if (existing) { + state = updateThreadState(existing, { + status: "running", + attempt_count: existing.attempt_count + 1, + last_run_url: updates.last_run_url ?? existing.last_run_url, + branch: updates.branch ?? existing.branch, + resume_status: updates.resume_status ?? "not_attempted", + last_resume_error: updates.last_resume_error ?? "", + resumed_from_session_id: updates.resumed_from_session_id ?? "", + forked_from_thread_key: updates.forked_from_thread_key ?? existing.forked_from_thread_key, + forked_from_acpx_session_id: updates.forked_from_acpx_session_id ?? existing.forked_from_acpx_session_id, + bundle_restore_status: updates.bundle_restore_status ?? existing.bundle_restore_status, + last_bundle_restore_error: updates.last_bundle_restore_error ?? existing.last_bundle_restore_error, + }); + } else { + state = updateThreadState(createThreadState(threadKey), { + status: "running", + attempt_count: 1, + last_run_url: updates.last_run_url ?? "", + branch: updates.branch ?? "", + resume_status: updates.resume_status ?? "not_attempted", + last_resume_error: updates.last_resume_error ?? "", + resumed_from_session_id: updates.resumed_from_session_id ?? "", + forked_from_thread_key: updates.forked_from_thread_key ?? "", + forked_from_acpx_session_id: updates.forked_from_acpx_session_id ?? "", + bundle_restore_status: updates.bundle_restore_status ?? "not_attempted", + last_bundle_restore_error: updates.last_bundle_restore_error ?? "", + }); + } + + writeThreadState(threadKey, state, cwd, opts); + return state; +} + +export interface ThreadStateCompletionUpdates { + acpxRecordId?: string; + acpxSessionId?: string; + agentSessionId?: string; + branch?: string; + last_comment_url?: string; + resume_status?: ThreadResumeStatus; + last_resume_error?: string; + resumed_from_session_id?: string; +} + +export function markThreadCompleted( + threadKey: string, + state: ThreadState, + cwd: string, + updates: ThreadStateCompletionUpdates, + opts?: PushOptions, +): ThreadState { + const next = updateThreadState(state, { + ...updates, + status: "completed", + }); + writeThreadState(threadKey, next, cwd, opts); + return next; +} + +export interface ThreadStateFailureUpdates { + last_comment_url?: string; + resume_status?: ThreadResumeStatus; + last_resume_error?: string; + resumed_from_session_id?: string; +} + +export function markThreadFailed( + threadKey: string, + state: ThreadState, + cwd: string, + updates: ThreadStateFailureUpdates, + opts?: PushOptions, +): ThreadState { + const next = updateThreadState(state, { + ...updates, + status: "failed", + }); + writeThreadState(threadKey, next, cwd, opts); + return next; +} + +export interface ThreadStateBundleRestoreUpdates { + bundle_restore_status?: ThreadBundleRestoreStatus; + last_bundle_restore_error?: string; +} + +export function markThreadBundleRestore( + threadKey: string, + cwd: string, + updates: ThreadStateBundleRestoreUpdates, + opts?: PushOptions, +): ThreadState | null { + const existing = fetchThreadState(threadKey, cwd, opts); + if (!existing) { + return null; + } + + const next = updateThreadState(existing, { + bundle_restore_status: updates.bundle_restore_status ?? existing.bundle_restore_status, + last_bundle_restore_error: updates.last_bundle_restore_error ?? existing.last_bundle_restore_error, + }); + writeThreadState(threadKey, next, cwd, opts); + return next; +} + +export interface ThreadStateBundleStoredUpdates { + session_bundle_backend?: string; + session_bundle_artifact_id?: string; + session_bundle_artifact_name?: string; + session_bundle_run_id?: string; +} + +export function markThreadBundleStored( + threadKey: string, + cwd: string, + updates: ThreadStateBundleStoredUpdates, + opts?: PushOptions, +): ThreadState { + const existing = fetchThreadState(threadKey, cwd, opts) || createThreadState(threadKey); + const next = updateThreadState(existing, { + session_bundle_backend: updates.session_bundle_backend ?? existing.session_bundle_backend, + session_bundle_artifact_id: updates.session_bundle_artifact_id ?? existing.session_bundle_artifact_id, + session_bundle_artifact_name: updates.session_bundle_artifact_name ?? existing.session_bundle_artifact_name, + session_bundle_run_id: updates.session_bundle_run_id ?? existing.session_bundle_run_id, + }); + writeThreadState(threadKey, next, cwd, opts); + return next; +} diff --git a/.agent/src/triage.ts b/.agent/src/triage.ts new file mode 100644 index 0000000..943e3b0 --- /dev/null +++ b/.agent/src/triage.ts @@ -0,0 +1,470 @@ +// Parses the structured JSON routing decision returned by the triage model +// and converts it into the portal's validated dispatch shape. + +import { escapeRegex, stripNonLiveMentions } from "./mentions.js"; +import { extractJsonObject } from "./response.js"; +import { + type AccessPolicy, + getAllowedAssociationsForRoute, + isAssociationAllowedForRoute, +} from "./access-policy.js"; + +export const ROUTES = new Set([ + "answer", + "implement", + "fix-pr", + "review", + "orchestrate", + "create-action", + "unsupported", +]); + +export interface DispatchDecision { + route: string; + needsApproval: boolean; + confidence: string; + summary: string; + issueTitle: string; + issueBody: string; + basePr?: string; +} + +const EXPLICIT_ROUTE_COMMANDS = ["answer", "implement", "fix-pr", "review", "orchestrate", "create-action"] as const; +const LABEL_ROUTE_PREFIX = "agent/"; +const LABEL_SKILL_PREFIX = "agent/s/"; +const VALID_SKILL_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; +const DEFAULT_IMPLEMENT_ISSUE_TITLE = "Implement requested change"; + +export interface RequestedLabelDecision { + route: string; + skill: string; +} + +export interface RequestedRouteDecision { + route: string; + skill: string; +} + +export interface ImplementIssueMetadata { + issueTitle: string; + issueBody: string; + basePr?: string; +} + +function normalizeOptionalBasePr(value: unknown): string { + if (value === undefined || value === null) { + return ""; + } + + const raw = String(value).trim(); + if (!raw) { + return ""; + } + if (!/^[1-9]\d*$/.test(raw)) { + throw new Error("Implement issue metadata base_pr must be a positive integer"); + } + + return raw; +} + +function fallbackImplementIssueBody(originalRequest: string): string { + return [ + "## Goal", + "Implement the requested change from the agent mention.", + "", + "## Original request", + originalRequest, + "", + "## Acceptance criteria", + "- Implement the requested change.", + "- Preserve existing behavior unless the request requires a change.", + "- Update tests or validation as needed.", + ].join("\n"); +} + +export function normalizeImplementIssueMetadata(raw: string): ImplementIssueMetadata { + const text = (raw ?? "").trim(); + if (!text) { + throw new Error("Implement issue metadata output was empty"); + } + + const jsonStr = extractJsonObject(text); + if (!jsonStr) { + throw new Error("Implement issue metadata output did not contain a JSON object"); + } + + const payload = JSON.parse(jsonStr) as Record; + const issueTitle = String(payload.issue_title || payload.issueTitle || "") + .replace(/[\r\n]+/g, " ") + .replace(/\s+/g, " ") + .trim(); + const issueBody = String(payload.issue_body || payload.issueBody || "").trim(); + const basePr = normalizeOptionalBasePr(payload.base_pr ?? payload.basePr); + + if (!issueTitle) { + throw new Error("Implement issue metadata output was missing issue_title"); + } + if (!issueBody) { + throw new Error("Implement issue metadata output was missing issue_body"); + } + + return { issueTitle, issueBody, basePr }; +} + +/** + * Extracts an explicit mention slash command such as + * `@sepo-agent /review` from the request body. + */ +export function extractRequestedRoute(body: string, mention: string): string { + return extractRequestedRouteDecision(body, mention).route; +} + +/** + * Extracts an explicit mention slash command decision such as + * `@sepo-agent /review` or `@sepo-agent /skill release-notes`. + */ +export function extractRequestedRouteDecision(body: string, mention: string): RequestedRouteDecision { + const sanitized = stripNonLiveMentions(String(body || "")); + const trimmedMention = String(mention || "").trim(); + if (!sanitized.trim() || !trimmedMention) { + return { route: "", skill: "" }; + } + + const routePattern = EXPLICIT_ROUTE_COMMANDS.map((route) => escapeRegex(route)).join("|"); + const explicitRegex = new RegExp( + `(?:^|[\\s(])${escapeRegex(trimmedMention)}\\s+/(${routePattern})(?=$|[\\s.,;:!?)\\]}])`, + "im", + ); + const explicitMatch = sanitized.match(explicitRegex); + if (explicitMatch) { + return { route: explicitMatch[1].toLowerCase(), skill: "" }; + } + + const skillRegex = new RegExp( + String.raw`(?:^|[\s(])${escapeRegex(trimmedMention)}\s+/skill\s+([A-Za-z0-9][A-Za-z0-9._-]*)(?=$|[\s.,;:!?)\]}])`, + "im", + ); + const skillMatch = sanitized.match(skillRegex); + if (!skillMatch) { + return { route: "", skill: "" }; + } + + return { + route: "skill", + skill: skillMatch[1].toLowerCase(), + }; +} + +/** + * Builds a deterministic routing decision for explicit slash commands so the + * portal can skip the dispatch agent when the user already picked the route. + */ +export function buildRequestedRouteDecision( + route: string, + requestText: string, + implementMetadata?: ImplementIssueMetadata | null, +): DispatchDecision { + const normalizedRoute = String(route || "").trim().toLowerCase(); + if ( + normalizedRoute !== "skill" && + !EXPLICIT_ROUTE_COMMANDS.includes(normalizedRoute as (typeof EXPLICIT_ROUTE_COMMANDS)[number]) + ) { + throw new Error(`Unsupported explicit route: ${normalizedRoute || "missing"}`); + } + + if (normalizedRoute === "implement") { + const originalRequest = String(requestText || "").trim() || "No request text provided."; + const metadata = implementMetadata?.issueTitle && implementMetadata?.issueBody + ? implementMetadata + : null; + return { + route: "implement", + // Explicit /implement is itself the approval, so the portal skips the + // approval gate and dispatches agent-implement directly. The gate still + // applies to triaged implement decisions (see applyDispatchPolicy). + needsApproval: false, + confidence: "high", + summary: "I’ll start implementing this request.", + issueTitle: metadata?.issueTitle || DEFAULT_IMPLEMENT_ISSUE_TITLE, + issueBody: metadata?.issueBody || fallbackImplementIssueBody(originalRequest), + basePr: metadata?.basePr || "", + }; + } + + if (normalizedRoute === "create-action") { + const originalRequest = String(requestText || "").trim() || "No request text provided."; + return { + route: "create-action", + needsApproval: false, + confidence: "high", + summary: "I’ll create a pull request for a scheduled agent workflow.", + issueTitle: "Create scheduled agent workflow", + issueBody: [ + "## Goal", + "Create a scheduled GitHub Actions workflow from the agent mention.", + "", + "## Original request", + originalRequest, + "", + "## Acceptance criteria", + "- Add or update one standalone workflow under `.github/workflows/`.", + "- Use native GitHub Actions triggers for schedule/manual runs.", + "- Include an expiration guard before running the agent task.", + "- Preserve activation through normal PR review and merge.", + ].join("\n"), + }; + } + + if (normalizedRoute === "fix-pr") { + return { + route: "fix-pr", + needsApproval: false, + confidence: "high", + summary: "I’ll start a PR fix pass.", + issueTitle: "", + issueBody: "", + }; + } + + if (normalizedRoute === "review") { + return { + route: "review", + needsApproval: false, + confidence: "high", + summary: "I’ll start a review pass.", + issueTitle: "", + issueBody: "", + }; + } + + if (normalizedRoute === "orchestrate") { + return { + route: "orchestrate", + needsApproval: false, + confidence: "high", + summary: "I’ll start orchestration for this target.", + issueTitle: "", + issueBody: "", + }; + } + + if (normalizedRoute === "skill") { + return { + route: "skill", + needsApproval: false, + confidence: "high", + summary: "I’ll run the requested skill.", + issueTitle: "", + issueBody: "", + }; + } + + return { + route: "answer", + needsApproval: false, + confidence: "high", + summary: "I’ll answer inline.", + issueTitle: "", + issueBody: "", + }; +} + +/** + * Resolves deterministic label-based routes. Unknown `agent/*` labels return null. + */ +export function resolveRequestedLabel(labelName: string): RequestedLabelDecision | null { + const raw = String(labelName || "").trim(); + if (!raw) { + return null; + } + + const normalized = raw.toLowerCase(); + if (!normalized.startsWith(LABEL_ROUTE_PREFIX)) { + return null; + } + + if (normalized === "agent/answer") { + return { route: "answer", skill: "" }; + } + if (normalized === "agent/implement") { + return { route: "implement", skill: "" }; + } + if (normalized === "agent/fix-pr") { + return { route: "fix-pr", skill: "" }; + } + if (normalized === "agent/review") { + return { route: "review", skill: "" }; + } + if (normalized === "agent/orchestrate") { + return { route: "orchestrate", skill: "" }; + } + if (normalized === "agent/create-action") { + return { route: "create-action", skill: "" }; + } + if (normalized.startsWith(LABEL_SKILL_PREFIX)) { + const skill = raw.slice(LABEL_SKILL_PREFIX.length).trim().toLowerCase(); + if (!skill || !VALID_SKILL_LABEL.test(skill)) { + return null; + } + return { route: "skill", skill }; + } + + return null; +} + +/** + * Validates and normalizes the portal dispatch decision emitted by the model. + */ +export function normalizeDispatch(raw: string): DispatchDecision { + const text = (raw ?? "").trim(); + if (!text) { + throw new Error("Dispatch output was empty"); + } + + const jsonStr = extractJsonObject(text); + if (!jsonStr) { + throw new Error("Dispatch output did not contain a JSON object"); + } + + const payload = JSON.parse(jsonStr) as Record; + const route = String(payload.route || "").toLowerCase(); + if (!ROUTES.has(route)) { + throw new Error(`Unsupported dispatch route: ${route || "missing"}`); + } + + return { + route, + needsApproval: Boolean(payload.needs_approval), + confidence: String(payload.confidence || "").trim().toLowerCase(), + summary: String(payload.summary || "").trim(), + issueTitle: String(payload.issue_title || "").trim(), + issueBody: String(payload.issue_body || "").trim(), + }; +} + +/** + * Applies repository policy to the model-emitted dispatch decision so approval + * requirements do not depend on the model getting control flags exactly right. + */ +export function applyDispatchPolicy( + decision: DispatchDecision, + targetKind: string, + authorAssociation?: string, + accessPolicy: AccessPolicy = { routeOverrides: {} }, + isPublicRepo = false, + isExplicit = false, +): DispatchDecision { + const normalized = { ...decision }; + + if ( + String(authorAssociation || "").trim() && + !isAssociationAllowedForRoute( + accessPolicy, + normalized.route, + authorAssociation || "", + isPublicRepo, + ) + ) { + const allowed = getAllowedAssociationsForRoute( + accessPolicy, + normalized.route, + isPublicRepo, + ); + return { + ...normalized, + route: "unsupported", + needsApproval: false, + summary: `${normalized.route} requests currently require ${allowed.join(", ")} access.`, + issueTitle: "", + issueBody: "", + }; + } + + if (normalized.route === "implement") { + // Triaged implement always requires approval as a false-positive guard; + // explicit /implement (slash command or agent/implement label) skips the + // gate because the user already stated the intent. + normalized.needsApproval = !isExplicit; + return normalized; + } + + if (normalized.route === "create-action") { + normalized.needsApproval = !isExplicit; + if (!normalized.issueTitle) { + normalized.issueTitle = "Create scheduled agent workflow"; + } + if (!normalized.issueBody) { + normalized.issueBody = "Create a scheduled GitHub Actions workflow for the requested automation."; + } + return normalized; + } + + if (normalized.route === "fix-pr") { + if (targetKind !== "pull_request") { + return { + ...normalized, + route: "unsupported", + needsApproval: false, + summary: + "PR fix requests are only supported from pull requests right now.", + issueTitle: "", + issueBody: "", + }; + } + + normalized.needsApproval = false; + normalized.issueTitle = ""; + normalized.issueBody = ""; + return normalized; + } + + if (normalized.route === "review") { + if (targetKind !== "pull_request") { + return { + ...normalized, + route: "unsupported", + needsApproval: false, + summary: + "Review requests are only supported from pull requests right now.", + issueTitle: "", + issueBody: "", + }; + } + + normalized.needsApproval = false; + normalized.issueTitle = ""; + normalized.issueBody = ""; + return normalized; + } + + if (normalized.route === "orchestrate") { + if (targetKind !== "issue" && targetKind !== "pull_request") { + return { + ...normalized, + route: "unsupported", + needsApproval: false, + summary: + "Orchestration requests are currently supported on issues and pull requests only.", + issueTitle: "", + issueBody: "", + }; + } + + normalized.needsApproval = false; + normalized.issueTitle = ""; + normalized.issueBody = ""; + return normalized; + } + + if (normalized.route === "skill") { + normalized.needsApproval = false; + normalized.issueTitle = ""; + normalized.issueBody = ""; + return normalized; + } + + normalized.needsApproval = false; + normalized.issueTitle = ""; + normalized.issueBody = ""; + return normalized; +} diff --git a/.agent/src/trigger-labels.ts b/.agent/src/trigger-labels.ts new file mode 100644 index 0000000..4588a69 --- /dev/null +++ b/.agent/src/trigger-labels.ts @@ -0,0 +1,45 @@ +export interface TriggerLabel { + name: string; + route: string; + description: string; + color: string; +} + +export const BUILT_IN_TRIGGER_LABELS: TriggerLabel[] = [ + { + name: "agent/answer", + route: "answer", + description: "Ask Sepo to answer a question or provide plan-only guidance", + color: "1f883d", + }, + { + name: "agent/implement", + route: "implement", + description: "Ask Sepo to implement an issue through a pull request", + color: "0969da", + }, + { + name: "agent/create-action", + route: "create-action", + description: "Ask Sepo to propose a scheduled agent workflow", + color: "8250df", + }, + { + name: "agent/review", + route: "review", + description: "Ask Sepo to review a pull request", + color: "bf3989", + }, + { + name: "agent/fix-pr", + route: "fix-pr", + description: "Ask Sepo to push fixes to a pull request branch", + color: "d1242f", + }, + { + name: "agent/orchestrate", + route: "orchestrate", + description: "Ask Sepo to run bounded follow-up orchestration", + color: "fb8c00", + }, +]; diff --git a/.agent/src/verify.ts b/.agent/src/verify.ts new file mode 100644 index 0000000..09f5827 --- /dev/null +++ b/.agent/src/verify.ts @@ -0,0 +1,51 @@ +// Post-agent verification helper. +// +// Runs lightweight checks on agent-generated changes. Delegates to the +// shared post-agent verification script while providing a typed interface +// for workflow use. + +import { execFileSync } from "node:child_process"; + +const VERIFY_SCRIPT = ".agent/scripts/post-agent-verify.sh"; + +export interface VerifyResult { + exitCode: number; + output: string; +} + +export interface VerifyOptions { + /** Optional base commit used to verify clean history-only HEAD updates. */ + baseSha?: string; +} + +export function shouldRunVerification(hasWorktreeChanges: boolean, hasBranchUpdate: boolean): boolean { + return hasWorktreeChanges || hasBranchUpdate; +} + +/** + * Runs the verification script. Returns exit code 0 if verification passed. + */ +export function runVerification(cwd: string, options: VerifyOptions = {}): VerifyResult { + try { + const env = { ...process.env }; + if (options.baseSha) { + env.VERIFY_BASE_SHA = options.baseSha; + } + + const output = execFileSync("bash", [VERIFY_SCRIPT], { + cwd, + env, + stdio: ["pipe", "pipe", "pipe"], + timeout: 120_000, + }).toString("utf8"); + return { exitCode: 0, output }; + } catch (err: unknown) { + const error = err as { status?: number; stdout?: Buffer; stderr?: Buffer }; + const stdout = error.stdout?.toString("utf8") ?? ""; + const stderr = error.stderr?.toString("utf8") ?? ""; + return { + exitCode: error.status ?? 1, + output: stdout + stderr, + }; + } +} diff --git a/.agent/tools/local-runner/.gitignore b/.agent/tools/local-runner/.gitignore new file mode 100644 index 0000000..22d29ef --- /dev/null +++ b/.agent/tools/local-runner/.gitignore @@ -0,0 +1,14 @@ +# Runner binaries, runtime, and work directories +actions-runner/ +runner-*/ +shared-tool-cache/ + +# Logs +*.log + +# Local environment files (do not commit registration tokens) +.env +.env.* + +# macOS +.DS_Store diff --git a/.agent/tools/local-runner/README.md b/.agent/tools/local-runner/README.md new file mode 100644 index 0000000..80fc76e --- /dev/null +++ b/.agent/tools/local-runner/README.md @@ -0,0 +1,166 @@ +# Local GitHub Actions Runner + +Scripts for running one or more self-hosted GitHub Actions runners on a local macOS machine. + +The repository is intentionally generic: provide your own GitHub organization or repository URL and a short-lived registration token when you set up the runners. + +## What this does + +- Downloads the GitHub Actions runner for your Mac (`osx-arm64` or `osx-x64`). +- Verifies the downloaded runner archive with the SHA-256 checksum from the GitHub runner release. +- Creates `runner-1`, `runner-2`, ... directories so each runner has its own working directory. +- Starts all configured runners and writes logs to `runner-N/runner.log`. +- Optionally installs a macOS `launchd` cleanup job that removes old runner diagnostic logs every 6 hours. + +## Requirements + +`bootstrap.sh` and `setup-runners.sh` run `check-requirements.sh` before registering runners. For the default agent workflows, the runner host needs: + +- macOS with Bash, `git`, `gh`, `jq`, `curl`, `tar`, and `shasum`. +- Node.js 22.x and npm. This matches the default `node_version` in `.github/actions/setup-agent-runtime` for self-hosted runners. +- Admin access to the target GitHub organization or repository so you can create a self-hosted runner registration token. +- Docker is optional. Docker cleanup is disabled unless you explicitly opt in. + +You do **not** need to preinstall `acpx`: each workflow runs `npm ci` in `.agent/`, and `acpx` is a package dependency exposed through `.agent/node_modules/.bin`. + +You also do **not** need to preinstall `codex` or `claude` for normal secret-backed runs. The shared `setup-agent-runtime` action installs the selected provider CLI when it is missing. If you want to rely on local provider authentication instead of repository secrets, authenticate the provider CLI as the same macOS user that runs the GitHub runner service. + +## Security note + +Use local self-hosted runners only for private repositories or repositories whose workflows and pull requests you trust. Public repository forks can run untrusted workflow code on self-hosted runner machines, including machines with local credentials and persistent workspace state. + +## Quick start + +1. Create a registration token in GitHub: + - Organization runner: `https://github.com/` → **Settings** → **Actions** → **Runners** → **New self-hosted runner**. + - Repository runner: `https://github.com//` → **Settings** → **Actions** → **Runners** → **New self-hosted runner**. + +2. Run the bootstrap script: + +```bash +./bootstrap.sh https://github.com/ +# or, for a repository-scoped runner: +./bootstrap.sh https://github.com// +``` + +To create multiple local runners: + +```bash +./bootstrap.sh https://github.com/ 3 +``` + +`bootstrap.sh` configures the runner(s), installs the cleanup schedule on macOS, and then starts the runners. Press `Ctrl+C` to stop them. + +> Registration tokens expire quickly. If setup fails with an authorization error, create a fresh token and run the command again. Do not commit tokens to the repository. + +## Manual commands + +Check host requirements without registering runners: + +```bash +./check-requirements.sh +``` + +Set up runners without starting them: + +```bash +./setup-runners.sh https://github.com/ 3 +``` + +Start all configured runners: + +```bash +./start-runners.sh +``` + +Stop all running runner processes: + +```bash +./stop-runners.sh +``` + +View logs: + +```bash +tail -f runner-*/runner.log +``` + +## Configuration + +You can customize setup with environment variables: + +| Variable | Default | Description | +| --- | --- | --- | +| `GITHUB_URL` | none | Target organization or repository URL when it is not passed as an argument. | +| `RUNNER_TOKEN` | none | Registration token when it is not passed as an argument. | +| `NUM_RUNNERS` | `1` | Number of runners when it is not passed as an argument. | +| `LOCAL_RUNNER_NODE_VERSION` | `22` | Required Node.js major version checked before registering runners. Match this to any custom `setup-agent-runtime` `node_version`. | +| `RUNNER_VERSION` | `2.332.0` | GitHub Actions runner version to download. | +| `RUNNER_SHA256` | release checksum | Optional explicit SHA-256 checksum for the selected runner archive; useful if release checksum lookup is rate-limited. | +| `GITHUB_TOKEN` | none | Optional token used only for runner release checksum lookup to avoid anonymous GitHub API rate limits. | +| `RUNNER_PLATFORM` | auto-detected | Runner package platform, usually `osx-arm64` or `osx-x64`. | +| `RUNNER_LABELS` | `self-hosted,macOS,ARM64` or `self-hosted,macOS,X64` | Labels passed to GitHub during runner registration. | +| `RUNNER_NAME_PREFIX` | `-runner` | Prefix for runner names. Runner numbers are appended. | +| `RUNNER_TOOL_CACHE` | `./shared-tool-cache` | Shared tool cache used when runners are started. | +| `LOCAL_RUNNER_DOCKER_PRUNE` | `0` | Set to `1` before running `bootstrap.sh` or `cleanup-runner.sh` to allow `docker system prune -f`. | + +Example: + +```bash +RUNNER_NAME_PREFIX=build-mac RUNNER_LABELS=self-hosted,macOS,ARM64,local \ + ./bootstrap.sh https://github.com/ 2 +``` + +## Cleanup job + +`cleanup-runner.sh` writes to `cleanup.log` and: + +- deletes runner diagnostic logs older than 7 days from `runner-*/_diag`. + +Docker pruning is disabled by default because it affects Docker resources outside these runners. To opt in: + +```bash +LOCAL_RUNNER_DOCKER_PRUNE=1 bash cleanup-runner.sh +``` + +To opt in for the scheduled cleanup job, set `LOCAL_RUNNER_DOCKER_PRUNE=1` when you run `bootstrap.sh`. + +`bootstrap.sh` renders `com.local-runner.cleanup.plist.template` with this repository's local absolute path, writes it to `~/Library/LaunchAgents/com.local-runner.cleanup.plist`, and loads it with `launchctl`. + +Check the scheduled job: + +```bash +launchctl list | grep local-runner.cleanup +``` + +Run cleanup manually: + +```bash +bash cleanup-runner.sh +tail -f cleanup.log +``` + +Disable the scheduled job: + +```bash +launchctl unload ~/Library/LaunchAgents/com.local-runner.cleanup.plist +rm ~/Library/LaunchAgents/com.local-runner.cleanup.plist +``` + +## Resetting runners + +To recreate a runner from scratch: + +1. Stop local runner processes: `./stop-runners.sh`. +2. Remove the runner from GitHub's **Actions → Runners** settings page. +3. Delete the matching local directory, for example `rm -rf runner-1`. +4. Run `setup-runners.sh` or `bootstrap.sh` again with a fresh registration token. + +## Files created locally + +The scripts create local runtime files that are ignored by Git: + +- `actions-runner/` — downloaded runner tarballs. +- `runner-*/` — configured runner directories and workspaces. +- `shared-tool-cache/` — reusable tool cache for started runners. +- `*.log` — runner and cleanup logs. diff --git a/.agent/tools/local-runner/bootstrap.sh b/.agent/tools/local-runner/bootstrap.sh new file mode 100755 index 0000000..2afafe0 --- /dev/null +++ b/.agent/tools/local-runner/bootstrap.sh @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +# One-stop setup: configure runner(s), install the cleanup schedule, and start running. +# +# Usage: +# ./bootstrap.sh [num_runners] +# +# Examples: +# ./bootstrap.sh https://github.com/my-org TOKEN +# ./bootstrap.sh https://github.com/my-org/my-repo TOKEN 3 + +set -euo pipefail + +GITHUB_URL=${1:-${GITHUB_URL:-}} +TOKEN=${2:-${RUNNER_TOKEN:-}} +NUM_RUNNERS=${3:-${NUM_RUNNERS:-1}} +BASE_DIR="$(cd "$(dirname "$0")" && pwd)" +PLIST_TEMPLATE="$BASE_DIR/com.local-runner.cleanup.plist.template" +PLIST_PATH="$HOME/Library/LaunchAgents/com.local-runner.cleanup.plist" +LOCAL_RUNNER_DOCKER_PRUNE=${LOCAL_RUNNER_DOCKER_PRUNE:-0} + +xml_escape() { + printf '%s' "$1" \ + | sed \ + -e 's/&/\&/g' \ + -e 's//\>/g' \ + -e 's/"/\"/g' \ + -e "s/'/\'/g" +} + +sed_replacement_escape() { + printf '%s' "$1" | sed 's/[\\&|]/\\&/g' +} + +usage() { + echo "Usage: $0 [num_runners]" + echo "" + echo "Examples:" + echo " $0 https://github.com/my-org TOKEN" + echo " $0 https://github.com/my-org/my-repo TOKEN 3" + echo "" + echo "Create a token from GitHub Settings → Actions → Runners → New self-hosted runner." +} + +if [ -z "$GITHUB_URL" ] || [ -z "$TOKEN" ]; then + usage + exit 1 +fi + +if ! [[ "$NUM_RUNNERS" =~ ^[0-9]+$ ]] || [ "$NUM_RUNNERS" -lt 1 ]; then + echo "num_runners must be a positive integer." + exit 1 +fi + +if [ "$LOCAL_RUNNER_DOCKER_PRUNE" != "0" ] && [ "$LOCAL_RUNNER_DOCKER_PRUNE" != "1" ]; then + echo "LOCAL_RUNNER_DOCKER_PRUNE must be 0 or 1." + exit 1 +fi + +case "$GITHUB_URL" in + http://*|https://*) ;; + *) + echo "github_url must be a URL, for example: https://github.com/my-org" + exit 1 + ;; +esac + +echo "=== Step 0: Check runner host requirements ===" +bash "$BASE_DIR/check-requirements.sh" + +echo "" +echo "=== Step 1: Setup runner(s) ===" +LOCAL_RUNNER_REQUIREMENTS_CHECKED=1 bash "$BASE_DIR/setup-runners.sh" "$GITHUB_URL" "$TOKEN" "$NUM_RUNNERS" + +echo "" +echo "=== Step 2: Activate cleanup schedule (every 6 hours) ===" +if [ "$(uname -s)" = "Darwin" ]; then + if [ ! -f "$PLIST_TEMPLATE" ]; then + echo "Missing launchd template: $PLIST_TEMPLATE" + exit 1 + fi + + mkdir -p "$HOME/Library/LaunchAgents" + + if [ -L "$PLIST_PATH" ] || [ -f "$PLIST_PATH" ]; then + launchctl unload "$PLIST_PATH" 2>/dev/null || true + rm -f "$PLIST_PATH" + fi + + # Render the template with this checkout's absolute path. Escape first for XML, + # then for sed replacement syntax so XML-sensitive path characters remain valid. + ESCAPED_BASE_DIR=$(sed_replacement_escape "$(xml_escape "$BASE_DIR")") + sed \ + -e "s|__PROJECT_DIR__|$ESCAPED_BASE_DIR|g" \ + -e "s|__LOCAL_RUNNER_DOCKER_PRUNE__|$LOCAL_RUNNER_DOCKER_PRUNE|g" \ + "$PLIST_TEMPLATE" > "$PLIST_PATH" + + launchctl load "$PLIST_PATH" + echo "Cleanup scheduled: $PLIST_PATH" +else + echo "Skipping launchd setup because this is not macOS. Run cleanup-runner.sh manually if needed." +fi + +echo "" +echo "=== Step 3: Starting runner(s) ===" +exec bash "$BASE_DIR/start-runners.sh" diff --git a/.agent/tools/local-runner/check-requirements.sh b/.agent/tools/local-runner/check-requirements.sh new file mode 100755 index 0000000..6f6103d --- /dev/null +++ b/.agent/tools/local-runner/check-requirements.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# Verify that this macOS host has the tools the agent workflows expect on a +# self-hosted runner. Provider CLIs are handled by setup-agent-runtime, so this +# script focuses on host tools that must exist before a workflow starts. + +set -euo pipefail + +REQUIRED_NODE_MAJOR=${LOCAL_RUNNER_NODE_VERSION:-22} + +missing=() +for cmd in git gh jq curl tar shasum node npm; do + if ! command -v "$cmd" >/dev/null 2>&1; then + missing+=("$cmd") + fi +done + +if [ "${#missing[@]}" -ne 0 ]; then + echo "Missing required runner tools: ${missing[*]}" >&2 + echo "" >&2 + echo "Install the missing tools before registering local agent runners." >&2 + echo "On macOS with Homebrew, this usually means:" >&2 + echo " brew install git gh jq node@22" >&2 + echo "" >&2 + echo "The agent workflows install acpx and provider CLIs as needed, but they" >&2 + echo "require these base tools to be available before the workflow starts." >&2 + exit 1 +fi + +installed_node=$(node -p 'process.versions.node') +installed_npm=$(npm --version) +installed_node_major=${installed_node%%.*} + +if [ -n "$REQUIRED_NODE_MAJOR" ] && [ "$installed_node_major" != "$REQUIRED_NODE_MAJOR" ]; then + echo "Node.js ${installed_node} is installed, but agent workflows currently require ${REQUIRED_NODE_MAJOR}.x on self-hosted runners." >&2 + echo "Install Node.js ${REQUIRED_NODE_MAJOR}.x, or set LOCAL_RUNNER_NODE_VERSION to match a custom setup-agent-runtime node_version." >&2 + exit 1 +fi + +echo "Base runner tools available." +echo "Node.js: ${installed_node}" +echo "npm: ${installed_npm}" + +npm_global_prefix=$(npm prefix -g 2>/dev/null || true) +if [ -n "$npm_global_prefix" ] && [ ! -w "$npm_global_prefix" ] && [ ! -w "$(dirname "$npm_global_prefix")" ]; then + echo "Warning: npm global prefix is not writable by this user: $npm_global_prefix" >&2 + echo "If a workflow needs to install Codex, preinstall it or use a user-writable Node/npm installation." >&2 +fi + +echo "" +echo "Agent runtime tools:" +echo "- acpx is installed per workflow by npm ci from .agent/package.json; no host install is required." +echo "- codex and claude are installed on demand by .github/actions/setup-agent-runtime when the selected provider needs them." +echo "- if you rely on local provider auth instead of repository secrets, authenticate the provider CLI as this macOS user before running jobs." + +if command -v codex >/dev/null 2>&1; then + echo "Optional Codex CLI: found ($(command -v codex))" +else + echo "Optional Codex CLI: not found; workflows can install it when needed." +fi + +if command -v claude >/dev/null 2>&1; then + echo "Optional Claude CLI: found ($(command -v claude))" +else + echo "Optional Claude CLI: not found; workflows can install it when needed." +fi diff --git a/.agent/tools/local-runner/cleanup-runner.sh b/.agent/tools/local-runner/cleanup-runner.sh new file mode 100755 index 0000000..0bdff21 --- /dev/null +++ b/.agent/tools/local-runner/cleanup-runner.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Cleanup script for local self-hosted GitHub Actions runners. +# Intended to run every 6 hours via launchd on macOS. + +set -euo pipefail + +BASE_DIR="$(cd "$(dirname "$0")" && pwd)" +LOG_FILE="$BASE_DIR/cleanup.log" +exec >> "$LOG_FILE" 2>&1 + +echo "=== Cleanup started: $(date) ===" + +if [ "${LOCAL_RUNNER_DOCKER_PRUNE:-0}" = "1" ]; then + if command -v docker >/dev/null 2>&1; then + echo "Pruning unused Docker containers, images, and networks..." + docker system prune -f 2>/dev/null || echo "Docker prune skipped (Docker not running or not reachable)." + else + echo "Docker not installed; skipping Docker prune." + fi +else + echo "Docker prune disabled. Set LOCAL_RUNNER_DOCKER_PRUNE=1 to enable it." +fi + +# Remove old runner diagnostic logs (older than 7 days) from all configured runners. +echo "Cleaning runner diagnostic logs older than 7 days..." +find "$BASE_DIR" -path "$BASE_DIR/runner-*/_diag/*.log" -type f -mtime +7 -delete 2>/dev/null || true + +echo "Disk: $(df -h / | awk 'NR==2{print $4 " free"}')" +echo "=== Cleanup finished: $(date) ===" diff --git a/.agent/tools/local-runner/com.local-runner.cleanup.plist.template b/.agent/tools/local-runner/com.local-runner.cleanup.plist.template new file mode 100644 index 0000000..14c58fc --- /dev/null +++ b/.agent/tools/local-runner/com.local-runner.cleanup.plist.template @@ -0,0 +1,31 @@ + + + + + Label + com.local-runner.cleanup + + ProgramArguments + + /bin/bash + __PROJECT_DIR__/cleanup-runner.sh + + + StartInterval + 21600 + + EnvironmentVariables + + LOCAL_RUNNER_DOCKER_PRUNE + __LOCAL_RUNNER_DOCKER_PRUNE__ + + + RunAtLoad + + + StandardOutPath + __PROJECT_DIR__/cleanup-launchd.log + StandardErrorPath + __PROJECT_DIR__/cleanup-launchd.log + + diff --git a/.agent/tools/local-runner/setup-runners.sh b/.agent/tools/local-runner/setup-runners.sh new file mode 100755 index 0000000..7841ed6 --- /dev/null +++ b/.agent/tools/local-runner/setup-runners.sh @@ -0,0 +1,170 @@ +#!/usr/bin/env bash +# Set up one or more GitHub Actions self-hosted runners. +# +# Usage: +# ./setup-runners.sh [num_runners] +# +# Examples: +# ./setup-runners.sh https://github.com/my-org TOKEN +# ./setup-runners.sh https://github.com/my-org/my-repo TOKEN 3 + +set -euo pipefail + +GITHUB_URL=${1:-${GITHUB_URL:-}} +TOKEN=${2:-${RUNNER_TOKEN:-}} +NUM_RUNNERS=${3:-${NUM_RUNNERS:-1}} +BASE_DIR="$(cd "$(dirname "$0")" && pwd)" +RUNNER_VERSION=${RUNNER_VERSION:-2.332.0} + +usage() { + echo "Usage: $0 [num_runners]" + echo "" + echo "Examples:" + echo " $0 https://github.com/my-org TOKEN" + echo " $0 https://github.com/my-org/my-repo TOKEN 3" + echo "" + echo "Create a token from GitHub Settings → Actions → Runners → New self-hosted runner." +} + +detect_runner_platform() { + case "$(uname -s)-$(uname -m)" in + Darwin-arm64) + echo "osx-arm64" + ;; + Darwin-x86_64) + echo "osx-x64" + ;; + *) + echo "Unsupported platform: $(uname -s) $(uname -m). Set RUNNER_PLATFORM explicitly if a runner package exists for this machine." >&2 + exit 1 + ;; + esac +} + +runner_arch_label() { + case "$1" in + *arm64*) echo "ARM64" ;; + *x64*) echo "X64" ;; + *) echo "$1" ;; + esac +} + +escape_basic_regex() { + printf '%s' "$1" | sed 's/[][\\.^$*]/\\&/g' +} + +runner_release_metadata() { + if [ -n "${GITHUB_TOKEN:-}" ]; then + curl -fsSL \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + "https://api.github.com/repos/actions/runner/releases/tags/v${RUNNER_VERSION}" + else + curl -fsSL "https://api.github.com/repos/actions/runner/releases/tags/v${RUNNER_VERSION}" + fi +} + +runner_release_body() { + runner_release_metadata | jq -r '.body // ""' +} + +runner_sha256() { + if [ -n "${RUNNER_SHA256:-}" ]; then + echo "$RUNNER_SHA256" + return + fi + + escaped_asset=$(escape_basic_regex "$RUNNER_ASSET") + runner_release_body \ + | sed -n "s/.*${escaped_asset}.*BEGIN SHA ${RUNNER_PLATFORM} -->\([0-9a-f]\{64\}\)<.*/\1/p" +} + +verify_runner_tarball() { + expected_sha=$(runner_sha256) + + if [ -z "$expected_sha" ]; then + echo "Unable to find SHA-256 checksum for $RUNNER_ASSET. Set RUNNER_SHA256 explicitly to continue." >&2 + exit 1 + fi + + actual_sha=$(shasum -a 256 "$RUNNER_TAR" | awk '{print $1}') + + if [ "$actual_sha" != "$expected_sha" ]; then + echo "Checksum mismatch for $RUNNER_TAR" >&2 + echo "expected: $expected_sha" >&2 + echo "actual: $actual_sha" >&2 + exit 1 + fi +} + +if [ -z "$GITHUB_URL" ] || [ -z "$TOKEN" ]; then + usage + exit 1 +fi + +if ! [[ "$NUM_RUNNERS" =~ ^[0-9]+$ ]] || [ "$NUM_RUNNERS" -lt 1 ]; then + echo "num_runners must be a positive integer." + exit 1 +fi + +case "$GITHUB_URL" in + http://*|https://*) ;; + *) + echo "github_url must be a URL, for example: https://github.com/my-org" + exit 1 + ;; +esac + +if [ "${LOCAL_RUNNER_REQUIREMENTS_CHECKED:-0}" != "1" ]; then + bash "$BASE_DIR/check-requirements.sh" +fi + +RUNNER_PLATFORM=${RUNNER_PLATFORM:-$(detect_runner_platform)} +DEFAULT_LABELS="self-hosted,macOS,$(runner_arch_label "$RUNNER_PLATFORM")" +RUNNER_LABELS=${RUNNER_LABELS:-$DEFAULT_LABELS} +DEFAULT_RUNNER_NAME_PREFIX="$(hostname -s 2>/dev/null || hostname)-runner" +RUNNER_NAME_PREFIX=${RUNNER_NAME_PREFIX:-$DEFAULT_RUNNER_NAME_PREFIX} +RUNNER_CACHE_DIR="$BASE_DIR/actions-runner" +RUNNER_ASSET="actions-runner-${RUNNER_PLATFORM}-${RUNNER_VERSION}.tar.gz" +RUNNER_TAR="$RUNNER_CACHE_DIR/$RUNNER_ASSET" +RUNNER_URL="https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/$RUNNER_ASSET" + +mkdir -p "$RUNNER_CACHE_DIR" + +if [ ! -f "$RUNNER_TAR" ]; then + echo "Downloading GitHub Actions runner $RUNNER_VERSION for $RUNNER_PLATFORM..." + curl -fL -o "$RUNNER_TAR" "$RUNNER_URL" +fi + +echo "Verifying $RUNNER_ASSET..." +verify_runner_tarball + +for i in $(seq 1 "$NUM_RUNNERS"); do + RUNNER_DIR="$BASE_DIR/runner-$i" + RUNNER_NAME="$RUNNER_NAME_PREFIX-$i" + + if [ -d "$RUNNER_DIR" ] && [ -f "$RUNNER_DIR/.runner" ]; then + echo "Runner $i already configured at $RUNNER_DIR; skipping setup." + continue + fi + + echo "=== Setting up runner $i in $RUNNER_DIR ===" + mkdir -p "$RUNNER_DIR" + tar xzf "$RUNNER_TAR" -C "$RUNNER_DIR" + + ( + cd "$RUNNER_DIR" + ./config.sh --url "$GITHUB_URL" \ + --token "$TOKEN" \ + --name "$RUNNER_NAME" \ + --labels "$RUNNER_LABELS" \ + --unattended \ + --replace + ) + + echo "Runner $i configured as $RUNNER_NAME." +done + +echo "" +echo "All $NUM_RUNNERS runner(s) configured. Start them with:" +echo " ./start-runners.sh" diff --git a/.agent/tools/local-runner/start-runners.sh b/.agent/tools/local-runner/start-runners.sh new file mode 100755 index 0000000..2e798a9 --- /dev/null +++ b/.agent/tools/local-runner/start-runners.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# Start all configured runners in background processes. +# Logs go to runner-N/runner.log. + +set -euo pipefail + +BASE_DIR="$(cd "$(dirname "$0")" && pwd)" +PIDS=() + +cleanup() { + echo "" + echo "Stopping all runners..." + for pid in "${PIDS[@]}"; do + kill "$pid" 2>/dev/null || true + done + wait 2>/dev/null || true + echo "All runners stopped." +} + +trap cleanup SIGINT SIGTERM + +# Share tool cache (Node, Python, etc.) across all runners to avoid re-downloading. +export RUNNER_TOOL_CACHE="${RUNNER_TOOL_CACHE:-$BASE_DIR/shared-tool-cache}" +mkdir -p "$RUNNER_TOOL_CACHE" + +# Ask the GitHub runner wrapper to trap signals and forward them to the +# Runner.Listener process group. Without this, killing the backgrounded run.sh +# wrapper can leave listeners alive after Ctrl+C/SIGTERM. +export RUNNER_MANUALLY_TRAP_SIG=1 + +echo "Starting runners..." + +for dir in "$BASE_DIR"/runner-*/; do + [ -d "$dir" ] || continue + [ -f "$dir/.runner" ] || { echo "Skipping unconfigured dir: $dir"; continue; } + + name=$(basename "$dir") + echo "Starting $name (log: $dir/runner.log)" + + (cd "$dir" && ./run.sh >> runner.log 2>&1) & + PIDS+=($!) +done + +if [ ${#PIDS[@]} -eq 0 ]; then + echo "No configured runners found. Run setup-runners.sh first." + exit 1 +fi + +echo "" +echo "${#PIDS[@]} runner(s) started. Press Ctrl+C to stop all." +echo "To view logs: tail -f $BASE_DIR/runner-*/runner.log" + +wait diff --git a/.agent/tools/local-runner/stop-runners.sh b/.agent/tools/local-runner/stop-runners.sh new file mode 100755 index 0000000..75e37af --- /dev/null +++ b/.agent/tools/local-runner/stop-runners.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Stop all running GitHub Actions runner processes created from runner-* directories. + +set -euo pipefail + +BASE_DIR="$(cd "$(dirname "$0")" && pwd)" +FOUND=0 + +for dir in "$BASE_DIR"/runner-*/; do + [ -d "$dir" ] || continue + FOUND=1 + runner_path="${dir%/}" + name=$(basename "$runner_path") + + pids=$(pgrep -f "$runner_path/bin/Runner.Listener" 2>/dev/null || true) + if [ -n "$pids" ]; then + echo "Stopping $name (PID(s): $(echo "$pids" | tr '\n' ' '))" + kill $pids 2>/dev/null || true + else + echo "$name is not running" + fi +done + +if [ "$FOUND" -eq 0 ]; then + echo "No runner-* directories found." +fi + +echo "Done." diff --git a/.agent/tsconfig.json b/.agent/tsconfig.json new file mode 100644 index 0000000..cdff258 --- /dev/null +++ b/.agent/tsconfig.json @@ -0,0 +1,20 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "commonjs", + "moduleResolution": "node", + "lib": ["ES2022"], + "outDir": "dist", + "rootDir": "src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true + }, + "include": ["src/**/*.ts"], + "exclude": ["node_modules", "dist"] +} diff --git a/.github/actions/check-agent-action-expiration/action.yml b/.github/actions/check-agent-action-expiration/action.yml new file mode 100644 index 0000000..0de870c --- /dev/null +++ b/.github/actions/check-agent-action-expiration/action.yml @@ -0,0 +1,28 @@ +name: Check Agent Action Expiration +description: "Checks whether a generated scheduled agent action is past its YYYY-MM-DD expiration date." + +inputs: + expires_at: + description: "Expiration date in UTC, formatted as YYYY-MM-DD. The action is expired after this date." + required: true + +outputs: + expired: + description: "true when the current UTC date is after expires_at; otherwise false." + value: ${{ steps.check.outputs.expired }} + expires_at: + description: "The normalized expiration date." + value: ${{ steps.check.outputs.expires_at }} + today: + description: "The current UTC date used for comparison." + value: ${{ steps.check.outputs.today }} + +runs: + using: composite + steps: + - name: Check expiration + id: check + shell: bash + env: + INPUT_EXPIRES_AT: ${{ inputs.expires_at }} + run: bash "${GITHUB_ACTION_PATH}/check-expiration.sh" diff --git a/.github/actions/check-agent-action-expiration/check-expiration.sh b/.github/actions/check-agent-action-expiration/check-expiration.sh new file mode 100755 index 0000000..5c8cbb1 --- /dev/null +++ b/.github/actions/check-agent-action-expiration/check-expiration.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +set -euo pipefail + +expires_at="${INPUT_EXPIRES_AT:-}" + +fail() { + echo "::error title=Invalid expiration date::$1" >&2 + exit 2 +} + +if [[ -z "$expires_at" ]]; then + fail "expires_at is required and must be formatted as YYYY-MM-DD" +fi + +if [[ ! "$expires_at" =~ ^([0-9]{4})-([0-9]{2})-([0-9]{2})$ ]]; then + fail "expires_at must be formatted as YYYY-MM-DD" +fi + +year="${BASH_REMATCH[1]}" +month="${BASH_REMATCH[2]}" +day="${BASH_REMATCH[3]}" + +year_num=$((10#$year)) +month_num=$((10#$month)) +day_num=$((10#$day)) + +if (( month_num < 1 || month_num > 12 )); then + fail "expires_at month must be between 01 and 12" +fi + +is_leap_year=false +if (( (year_num % 4 == 0 && year_num % 100 != 0) || year_num % 400 == 0 )); then + is_leap_year=true +fi + +case "$month_num" in + 1|3|5|7|8|10|12) max_day=31 ;; + 4|6|9|11) max_day=30 ;; + 2) + if [[ "$is_leap_year" == "true" ]]; then + max_day=29 + else + max_day=28 + fi + ;; + *) fail "expires_at month must be between 01 and 12" ;; +esac + +if (( day_num < 1 || day_num > max_day )); then + fail "expires_at day is invalid for the given month" +fi + +today="$(date -u +%Y-%m-%d)" +expired=false +if [[ "$today" > "$expires_at" ]]; then + expired=true +fi + +{ + echo "expired=$expired" + echo "expires_at=$expires_at" + echo "today=$today" +} >> "$GITHUB_OUTPUT" + +if [[ "$expired" == "true" ]]; then + echo "Agent action expired at $expires_at; skipping." +else + echo "Agent action is not expired (today: $today, expires: $expires_at)." +fi diff --git a/.github/actions/discussion-post-gate/action.yml b/.github/actions/discussion-post-gate/action.yml new file mode 100644 index 0000000..233d2da --- /dev/null +++ b/.github/actions/discussion-post-gate/action.yml @@ -0,0 +1,31 @@ +name: Discussion Post Gate +description: Check whether a repository can accept a discussion post before agent runtime setup. + +inputs: + github_token: + description: "GitHub token used to query repository discussion settings" + required: true + discussion_category: + description: "Discussion category required for the post" + required: true + +outputs: + skip: + description: "true when discussion posting is unavailable and later steps should skip" + value: ${{ steps.resolve.outputs.skip }} + reason: + description: "Human-readable gate decision reason" + value: ${{ steps.resolve.outputs.reason }} + +runs: + using: composite + steps: + - name: Resolve discussion post gate + id: resolve + shell: bash + env: + DISCUSSION_CATEGORY: ${{ inputs.discussion_category }} + GH_TOKEN: ${{ inputs.github_token }} + GITHUB_TOKEN: ${{ inputs.github_token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: bash "${GITHUB_WORKSPACE}/.agent/scripts/resolve-discussion-post-gate.sh" diff --git a/.github/actions/download-agent-memory/action.yml b/.github/actions/download-agent-memory/action.yml new file mode 100644 index 0000000..49bd448 --- /dev/null +++ b/.github/actions/download-agent-memory/action.yml @@ -0,0 +1,142 @@ +name: Download Agent Memory +description: | + Best-effort shallow clone of the dedicated agent memory branch into a + separate directory outside the tracked worktree so the agent can read + memory files without staging them for its feature-branch commits. + +inputs: + github_token: + description: "GitHub token used to clone the repository" + required: true + ref: + description: "Memory branch to clone" + required: false + default: agent/memory + path: + description: "Destination directory for the cloned memory checkout" + required: false + default: "" + continue_on_missing: + description: "When true, missing memory branches resolve to memory_available=false instead of failing" + required: false + default: "true" + bootstrap_if_missing: + description: "When true, bootstrap a new local memory checkout if the branch does not exist" + required: false + default: "false" + +outputs: + memory_available: + description: "Whether the requested memory branch was cloned successfully" + value: ${{ steps.download.outputs.memory_available }} + memory_dir: + description: "Absolute path to the cloned memory directory" + value: ${{ steps.download.outputs.memory_dir }} + memory_ref: + description: "Resolved memory ref" + value: ${{ steps.download.outputs.memory_ref }} + +runs: + using: composite + steps: + - name: Download memory branch + id: download + shell: bash + env: + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + INPUT_REPOSITORY: ${{ github.repository }} + INPUT_REF: ${{ inputs.ref }} + INPUT_PATH: ${{ inputs.path }} + INPUT_CONTINUE_ON_MISSING: ${{ inputs.continue_on_missing }} + INPUT_BOOTSTRAP_IF_MISSING: ${{ inputs.bootstrap_if_missing }} + run: | + set -euo pipefail + + repo="${INPUT_REPOSITORY}" + ref="${INPUT_REF}" + dest="${INPUT_PATH}" + + if [ -z "$repo" ]; then + echo "Missing memory repository." >&2 + exit 1 + fi + + if [ -z "$dest" ]; then + dest="${RUNNER_TEMP}/agent-memory" + fi + + case "$dest" in + /*) ;; + *) dest="${GITHUB_WORKSPACE}/${dest}" ;; + esac + + if [ -d "$dest" ]; then + rm -rf "$dest" + fi + mkdir -p "$(dirname "$dest")" + + auth_url="https://x-access-token:${INPUT_GITHUB_TOKEN}@github.com/${repo}.git" + clone_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-memory-clone.XXXXXX.log")" + bootstrap_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-memory-bootstrap.XXXXXX.log")" + lsremote_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-memory-lsremote.XXXXXX.log")" + trap 'rm -f "$clone_log" "$bootstrap_log" "$lsremote_log"' EXIT + + if git clone --depth=1 --branch "$ref" --single-branch "$auth_url" "$dest" > /dev/null 2>"$clone_log"; then + echo "memory_available=true" >> "$GITHUB_OUTPUT" + echo "memory_dir=$dest" >> "$GITHUB_OUTPUT" + echo "memory_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + else + clone_status=$? + fi + + if git ls-remote --exit-code --heads "$auth_url" "$ref" >/dev/null 2>"$lsremote_log"; then + if [ -s "$clone_log" ]; then + cat "$clone_log" >&2 + fi + echo "Failed to clone memory branch ${repo}@${ref}." >&2 + exit "$clone_status" + else + lsremote_status=$? + fi + + if [ "$lsremote_status" -eq 2 ]; then + if [ "$INPUT_BOOTSTRAP_IF_MISSING" = "true" ]; then + echo "Memory branch ${repo}@${ref} is not available; bootstrapping a new memory checkout." >&2 + if ! git clone --depth=1 "$auth_url" "$dest" > /dev/null 2>"$bootstrap_log"; then + if [ -s "$bootstrap_log" ]; then + cat "$bootstrap_log" >&2 + fi + echo "Failed to bootstrap memory checkout for ${repo}@${ref}." >&2 + exit 1 + fi + + cd "$dest" + git checkout --orphan "$ref" + git rm -rf . >/dev/null 2>&1 || true + git clean -fdx >/dev/null 2>&1 || true + node "${GITHUB_WORKSPACE}/.agent/dist/cli/memory/init.js" --dir "$dest" --repo "$repo" >/dev/null + + echo "memory_available=true" >> "$GITHUB_OUTPUT" + echo "memory_dir=$dest" >> "$GITHUB_OUTPUT" + echo "memory_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + fi + + if [ "$INPUT_CONTINUE_ON_MISSING" = "true" ]; then + echo "Memory branch ${repo}@${ref} is not available; continuing without memory." >&2 + echo "memory_available=false" >> "$GITHUB_OUTPUT" + echo "memory_dir=" >> "$GITHUB_OUTPUT" + echo "memory_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + fi + fi + + if [ -s "$clone_log" ]; then + cat "$clone_log" >&2 + fi + if [ -s "$lsremote_log" ]; then + cat "$lsremote_log" >&2 + fi + echo "Failed to clone memory branch ${repo}@${ref}." >&2 + exit "${clone_status:-1}" diff --git a/.github/actions/download-agent-rubrics/action.yml b/.github/actions/download-agent-rubrics/action.yml new file mode 100644 index 0000000..05009cf --- /dev/null +++ b/.github/actions/download-agent-rubrics/action.yml @@ -0,0 +1,142 @@ +name: Download Agent Rubrics +description: | + Best-effort shallow clone of the dedicated user/team rubric branch into a + separate directory outside the tracked worktree so agents can read rubrics + without staging them for feature-branch commits. + +inputs: + github_token: + description: "GitHub token used to clone the repository" + required: true + ref: + description: "Rubrics branch to clone" + required: false + default: agent/rubrics + path: + description: "Destination directory for the cloned rubrics checkout" + required: false + default: "" + continue_on_missing: + description: "When true, missing rubric branches resolve to rubrics_available=false instead of failing" + required: false + default: "true" + bootstrap_if_missing: + description: "When true, bootstrap a new local rubrics checkout if the branch does not exist" + required: false + default: "false" + +outputs: + rubrics_available: + description: "Whether the requested rubrics branch was cloned successfully" + value: ${{ steps.download.outputs.rubrics_available }} + rubrics_dir: + description: "Absolute path to the cloned rubrics directory" + value: ${{ steps.download.outputs.rubrics_dir }} + rubrics_ref: + description: "Resolved rubrics ref" + value: ${{ steps.download.outputs.rubrics_ref }} + +runs: + using: composite + steps: + - name: Download rubrics branch + id: download + shell: bash + env: + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + INPUT_REPOSITORY: ${{ github.repository }} + INPUT_REF: ${{ inputs.ref }} + INPUT_PATH: ${{ inputs.path }} + INPUT_CONTINUE_ON_MISSING: ${{ inputs.continue_on_missing }} + INPUT_BOOTSTRAP_IF_MISSING: ${{ inputs.bootstrap_if_missing }} + run: | + set -euo pipefail + + repo="${INPUT_REPOSITORY}" + ref="${INPUT_REF}" + dest="${INPUT_PATH}" + + if [ -z "$repo" ]; then + echo "Missing rubrics repository." >&2 + exit 1 + fi + + if [ -z "$dest" ]; then + dest="${RUNNER_TEMP}/agent-rubrics" + fi + + case "$dest" in + /*) ;; + *) dest="${GITHUB_WORKSPACE}/${dest}" ;; + esac + + if [ -d "$dest" ]; then + rm -rf "$dest" + fi + mkdir -p "$(dirname "$dest")" + + auth_url="https://x-access-token:${INPUT_GITHUB_TOKEN}@github.com/${repo}.git" + clone_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-rubrics-clone.XXXXXX.log")" + bootstrap_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-rubrics-bootstrap.XXXXXX.log")" + lsremote_log="$(mktemp "${RUNNER_TEMP:-/tmp}/download-agent-rubrics-lsremote.XXXXXX.log")" + trap 'rm -f "$clone_log" "$bootstrap_log" "$lsremote_log"' EXIT + + if git clone --depth=1 --branch "$ref" --single-branch "$auth_url" "$dest" > /dev/null 2>"$clone_log"; then + echo "rubrics_available=true" >> "$GITHUB_OUTPUT" + echo "rubrics_dir=$dest" >> "$GITHUB_OUTPUT" + echo "rubrics_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + else + clone_status=$? + fi + + if git ls-remote --exit-code --heads "$auth_url" "$ref" >/dev/null 2>"$lsremote_log"; then + if [ -s "$clone_log" ]; then + cat "$clone_log" >&2 + fi + echo "Failed to clone rubrics branch ${repo}@${ref}." >&2 + exit "$clone_status" + else + lsremote_status=$? + fi + + if [ "$lsremote_status" -eq 2 ]; then + if [ "$INPUT_BOOTSTRAP_IF_MISSING" = "true" ]; then + echo "Rubrics branch ${repo}@${ref} is not available; bootstrapping a new rubrics checkout." >&2 + if ! git clone --depth=1 "$auth_url" "$dest" > /dev/null 2>"$bootstrap_log"; then + if [ -s "$bootstrap_log" ]; then + cat "$bootstrap_log" >&2 + fi + echo "Failed to bootstrap rubrics checkout for ${repo}@${ref}." >&2 + exit 1 + fi + + cd "$dest" + git checkout --orphan "$ref" + git rm -rf . >/dev/null 2>&1 || true + git clean -fdx >/dev/null 2>&1 || true + node "${GITHUB_WORKSPACE}/.agent/dist/cli/rubrics/init.js" --dir "$dest" --repo "$repo" >/dev/null + + echo "rubrics_available=true" >> "$GITHUB_OUTPUT" + echo "rubrics_dir=$dest" >> "$GITHUB_OUTPUT" + echo "rubrics_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + fi + + if [ "$INPUT_CONTINUE_ON_MISSING" = "true" ]; then + echo "Rubrics branch ${repo}@${ref} is not available; continuing without rubric steering." >&2 + echo "rubrics_available=false" >> "$GITHUB_OUTPUT" + echo "rubrics_dir=" >> "$GITHUB_OUTPUT" + echo "rubrics_ref=$ref" >> "$GITHUB_OUTPUT" + exit 0 + fi + fi + + if [ -s "$clone_log" ]; then + cat "$clone_log" >&2 + fi + if [ -s "$lsremote_log" ]; then + cat "$lsremote_log" >&2 + fi + echo "Failed to clone rubrics branch ${repo}@${ref}." >&2 + exit "${clone_status:-1}" diff --git a/.github/actions/resolve-agent-provider/action.yml b/.github/actions/resolve-agent-provider/action.yml new file mode 100644 index 0000000..6339836 --- /dev/null +++ b/.github/actions/resolve-agent-provider/action.yml @@ -0,0 +1,59 @@ +name: Resolve Agent Provider +description: Resolve the acpx agent provider from route overrides, defaults, and configured secrets. + +inputs: + route: + description: "Route name used in diagnostics" + required: true + route_provider: + description: "Optional inline route-specific provider override" + required: false + default: "" + default_provider: + description: "Default provider: auto, codex, or claude" + required: false + default: auto + openai_api_key: + description: "OpenAI API key for Codex readiness detection" + required: false + default: "" + claude_oauth_token: + description: "Claude Code OAuth token for Claude readiness detection" + required: false + default: "" + required: + description: "Whether unresolved auto provider detection should fail the step" + required: false + default: "true" + +outputs: + provider: + description: "Resolved provider" + value: ${{ steps.resolve.outputs.provider }} + reason: + description: "Human-readable reason for the selected provider" + value: ${{ steps.resolve.outputs.reason }} + install_codex: + description: "Whether setup-agent-runtime should install Codex" + value: ${{ steps.resolve.outputs.install_codex }} + install_claude: + description: "Whether setup-agent-runtime should install Claude" + value: ${{ steps.resolve.outputs.install_claude }} + +runs: + using: composite + steps: + - name: Resolve provider + id: resolve + shell: bash + env: + ROUTE: ${{ inputs.route }} + ROUTE_PROVIDER: ${{ inputs.route_provider }} + DEFAULT_PROVIDER: ${{ inputs.default_provider }} + OPENAI_API_KEY: ${{ inputs.openai_api_key }} + CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude_oauth_token }} + REQUIRED: ${{ inputs.required }} + run: | + # Keep this as a composite-action shell helper, matching resolve-github-auth, + # because provider resolution runs before setup-agent-runtime builds .agent/dist. + bash "${GITHUB_ACTION_PATH}/resolve-provider.sh" diff --git a/.github/actions/resolve-agent-provider/resolve-provider.sh b/.github/actions/resolve-agent-provider/resolve-provider.sh new file mode 100644 index 0000000..efe6616 --- /dev/null +++ b/.github/actions/resolve-agent-provider/resolve-provider.sh @@ -0,0 +1,98 @@ +#!/usr/bin/env bash +set -euo pipefail + +normalize_provider() { + printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' +} + +validate_provider() { + case "$1" in + auto|codex|claude) return 0 ;; + *) return 1 ;; + esac +} + +write_outputs() { + echo "provider=${provider}" >> "$GITHUB_OUTPUT" + echo "reason=${reason}" >> "$GITHUB_OUTPUT" + echo "install_codex=$([ "$provider" = codex ] && echo true || echo false)" >> "$GITHUB_OUTPUT" + echo "install_claude=$([ "$provider" = claude ] && echo true || echo false)" >> "$GITHUB_OUTPUT" +} + +route="${ROUTE:-}" +route_provider="$(normalize_provider "${ROUTE_PROVIDER:-}")" +default_provider="$(normalize_provider "${DEFAULT_PROVIDER:-auto}")" +required="$(normalize_provider "${REQUIRED:-true}")" + +if [ -z "$default_provider" ]; then + default_provider=auto +fi + +case "$required" in + true|false) ;; + *) + echo "Invalid required flag '$required' for route '$route'. Use true or false." >&2 + exit 1 + ;; +esac + +has_codex=false +has_claude=false +if [ -n "${OPENAI_API_KEY:-}" ]; then + has_codex=true +fi +if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then + has_claude=true +fi + +for candidate in "$route_provider" "$default_provider"; do + if [ -n "$candidate" ] && ! validate_provider "$candidate"; then + echo "Invalid agent provider '$candidate' for route '$route'. Use auto, codex, or claude." >&2 + exit 1 + fi +done + +requested_provider="$default_provider" +requested_reason="AGENT_DEFAULT_PROVIDER" +explicit_provider=false +if [ -n "$route_provider" ]; then + requested_provider="$route_provider" + requested_reason="route override for $route" +fi +if [ "$requested_provider" != auto ]; then + explicit_provider=true +fi + +provider="" +reason="" +if [ "$explicit_provider" = true ]; then + provider="$requested_provider" + reason="$requested_reason" +elif [ "$has_codex" = true ]; then + # Keep auto mode deterministic and compatible with prior Codex-first behavior. + provider=codex + reason="OPENAI_API_KEY is configured" +elif [ "$has_claude" = true ]; then + provider=claude + reason="CLAUDE_CODE_OAUTH_TOKEN is configured" +else + echo "No configured agent provider for route '$route'. Set AGENT_DEFAULT_PROVIDER to codex or claude, or configure OPENAI_API_KEY or CLAUDE_CODE_OAUTH_TOKEN." >&2 + if [ "$required" = true ]; then + exit 1 + fi + provider="" + reason="no configured provider" + write_outputs + echo "Agent provider for $route is unresolved ($reason)." + exit 0 +fi + +if [ "$explicit_provider" = true ] && [ "$provider" = codex ] && [ "$has_codex" != true ]; then + echo "Resolved provider codex for route '$route' without OPENAI_API_KEY; relying on local Codex authentication if available." >&2 +fi +if [ "$explicit_provider" = true ] && [ "$provider" = claude ] && [ "$has_claude" != true ]; then + echo "Resolved provider claude for route '$route' without CLAUDE_CODE_OAUTH_TOKEN; relying on local Claude authentication if available." >&2 +fi + +write_outputs +echo "Resolved agent provider for $route: $provider ($reason)." diff --git a/.github/actions/resolve-github-auth/action.yml b/.github/actions/resolve-github-auth/action.yml new file mode 100644 index 0000000..c535763 --- /dev/null +++ b/.github/actions/resolve-github-auth/action.yml @@ -0,0 +1,103 @@ +name: Resolve GitHub auth +description: >- + Resolve the GitHub token source from direct app credentials, the official + hosted OIDC broker, PAT, or fallback token. Callers using the hosted OIDC + broker path must grant `permissions: id-token: write`. + +inputs: + app_id: + description: GitHub App ID. + required: false + default: "" + app_private_key: + description: GitHub App private key. + required: false + default: "" + pat: + description: Fine-grained PAT or machine-user token. + required: false + default: "" + fallback_token: + description: Fallback token, typically github.token. + required: false + default: "" + +outputs: + token: + description: Resolved GitHub token. + value: ${{ steps.resolve.outputs.token }} + auth_mode: + description: Which auth mode was selected (github_app, oidc_broker, pat, github_token). + value: ${{ steps.resolve.outputs.auth_mode }} + +runs: + using: composite + steps: + - name: Validate direct GitHub App inputs + shell: bash + env: + INPUT_APP_ID: ${{ inputs.app_id }} + INPUT_APP_PRIVATE_KEY: ${{ inputs.app_private_key }} + run: | + set -euo pipefail + + if { [ -n "${INPUT_APP_ID}" ] && [ -z "${INPUT_APP_PRIVATE_KEY}" ]; } || + { [ -z "${INPUT_APP_ID}" ] && [ -n "${INPUT_APP_PRIVATE_KEY}" ]; }; then + echo "app_id and app_private_key must be configured together." >&2 + exit 1 + fi + + - name: Generate app token + id: app-token + if: ${{ inputs.app_id != '' && inputs.app_private_key != '' }} + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ inputs.app_id }} + private-key: ${{ inputs.app_private_key }} + + - name: Exchange OIDC token for hosted app token + id: oidc-token + if: ${{ inputs.app_id == '' && inputs.app_private_key == '' }} + shell: bash + env: + OIDC_AUDIENCE: sepo + OIDC_EXCHANGE_URL: https://oidc.self-evolving.app/api/github/github-app-token-exchange + run: bash "${GITHUB_ACTION_PATH}/exchange-oidc.sh" + + - name: Resolve token source + id: resolve + shell: bash + env: + APP_TOKEN: ${{ steps.app-token.outputs.token }} + OIDC_TOKEN: ${{ steps.oidc-token.outputs.token }} + PAT_TOKEN: ${{ inputs.pat }} + FALLBACK_TOKEN: ${{ inputs.fallback_token }} + run: | + set -euo pipefail + + token="" + auth_mode="" + + if [ -n "$APP_TOKEN" ]; then + token="$APP_TOKEN" + auth_mode="github_app" + elif [ -n "$OIDC_TOKEN" ]; then + token="$OIDC_TOKEN" + auth_mode="oidc_broker" + elif [ -n "$PAT_TOKEN" ]; then + token="$PAT_TOKEN" + auth_mode="pat" + elif [ -n "$FALLBACK_TOKEN" ]; then + token="$FALLBACK_TOKEN" + auth_mode="github_token" + else + echo "No GitHub auth token source configured." >&2 + exit 1 + fi + + echo "Resolved auth mode: $auth_mode" + echo "::add-mask::$token" + { + echo "token=$token" + echo "auth_mode=$auth_mode" + } >> "$GITHUB_OUTPUT" diff --git a/.github/actions/resolve-github-auth/exchange-oidc.sh b/.github/actions/resolve-github-auth/exchange-oidc.sh new file mode 100644 index 0000000..da0803e --- /dev/null +++ b/.github/actions/resolve-github-auth/exchange-oidc.sh @@ -0,0 +1,116 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "token=" >> "$GITHUB_OUTPUT" +echo "auth_mode=" >> "$GITHUB_OUTPUT" + +if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; then + echo "OIDC token request environment is unavailable; skipping hosted broker auth." >&2 + exit 0 +fi + +for cmd in curl jq; do + if ! command -v "${cmd}" >/dev/null 2>&1; then + echo "Missing required tool for hosted broker auth: ${cmd}; skipping hosted broker auth." >&2 + exit 0 + fi +done + +run_with_retries() { + local __result_var="$1" + shift + local __attempt=1 + local __delay=1 + local __result="" + + while true; do + if __result="$("$@")"; then + printf -v "${__result_var}" '%s' "${__result}" + return 0 + fi + + if [ "${__attempt}" -ge 3 ]; then + return 1 + fi + + sleep "${__delay}" + __delay=$((__delay * 2)) + __attempt=$((__attempt + 1)) + done +} + +oidc_request_url="${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=${OIDC_AUDIENCE}" + +if ! run_with_retries oidc_response \ + curl --fail --silent --show-error --max-time 30 \ + -H "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \ + "${oidc_request_url}"; then + echo "Failed to fetch GitHub OIDC token; skipping hosted broker auth." >&2 + exit 0 +fi + +oidc_token="$(printf '%s' "${oidc_response}" | jq -r '.value // empty' 2>/dev/null || true)" +if [ -z "${oidc_token}" ]; then + echo "OIDC token response did not include a token value; skipping hosted broker auth." >&2 + exit 0 +fi +echo "::add-mask::${oidc_token}" + +exchange_request_file="$(mktemp)" +exchange_response_file="$(mktemp)" +trap 'rm -f "${exchange_request_file}" "${exchange_response_file}"' EXIT + +if ! jq -n \ + --arg oidc_token "${oidc_token}" \ + --arg repository "${GITHUB_REPOSITORY:-}" \ + --arg workflow_ref "${GITHUB_WORKFLOW_REF:-}" \ + --arg run_id "${GITHUB_RUN_ID:-}" \ + '{ + oidc_token: $oidc_token, + repository: $repository, + workflow_ref: $workflow_ref, + run_id: $run_id + }' > "${exchange_request_file}"; then + echo "Failed to build hosted broker exchange request; skipping hosted broker auth." >&2 + exit 0 +fi + +if ! run_with_retries exchange_status \ + curl --silent --show-error --max-time 30 \ + -o "${exchange_response_file}" \ + -w '%{http_code}' \ + -H 'Content-Type: application/json' \ + -X POST \ + "${OIDC_EXCHANGE_URL}" \ + --data-binary @"${exchange_request_file}"; then + echo "Hosted broker exchange request failed; skipping hosted broker auth." >&2 + exit 0 +fi + +if [ "${exchange_status}" -lt 200 ] || [ "${exchange_status}" -ge 300 ]; then + broker_message="$(jq -r '.error.message // .message // empty' "${exchange_response_file}" 2>/dev/null || true)" + if [ -n "${broker_message}" ]; then + echo "Hosted broker exchange returned HTTP ${exchange_status}: ${broker_message}" >&2 + else + echo "Hosted broker exchange returned HTTP ${exchange_status}; skipping hosted broker auth." >&2 + fi + exit 0 +fi + +exchange_token="$(jq -r '.token // .app_token // empty' "${exchange_response_file}" 2>/dev/null || true)" + +if [ -z "${exchange_token}" ]; then + broker_keys="$(jq -r 'if type == "object" then (keys_unsorted | join(",")) else empty end' "${exchange_response_file}" 2>/dev/null || true)" + if [ -n "${broker_keys}" ]; then + echo "Hosted broker exchange response did not include a token field (saw keys: ${broker_keys}); skipping hosted broker auth." >&2 + else + echo "Hosted broker exchange response did not include a token; skipping hosted broker auth." >&2 + fi + exit 0 +fi + +echo "::add-mask::${exchange_token}" +{ + echo "token=${exchange_token}" + echo "auth_mode=oidc_broker" +} >> "$GITHUB_OUTPUT" diff --git a/.github/actions/run-agent-task/action.yml b/.github/actions/run-agent-task/action.yml new file mode 100644 index 0000000..6b0dade --- /dev/null +++ b/.github/actions/run-agent-task/action.yml @@ -0,0 +1,482 @@ +name: Run Agent Task +description: | + Shared composite action for running an agent prompt via acpx. + Assumes the runtime has already been bootstrapped by setup-agent-runtime, + then handles envelope construction, prompt composition (_base.md + + optional _memory.md/_rubrics.md + template), optional session bundle + restore/backup, and acpx invocation through run.ts. + +inputs: + prompt: + description: "Built-in prompt name (resolves to .github/prompts/.md)" + required: false + skill: + description: "User-defined skill name (resolves to //SKILL.md)" + required: false + skill_root: + description: "Root directory for user-defined skills" + required: false + default: ".skills" + agent: + description: "acpx agent to use" + required: false + default: codex + permission_mode: + description: "acpx permission mode (approve-all, approve-reads, deny-all)" + required: false + default: approve-all + reasoning_effort: + description: "Model reasoning effort level" + required: false + default: xhigh + route: + description: "Envelope route (implement, review, fix-pr, answer, create-action, dispatch, agent-self-approve, agent-self-merge, skill, rubrics-review, rubrics-initialization, rubrics-update)" + required: true + lane: + description: "Logical lane for thread/session identity (defaults to 'default')" + required: false + default: "" + target_kind: + description: "Target kind (issue, pull_request, discussion, repository)" + required: true + target_number: + description: "Target number" + required: true + target_url: + description: "Target URL" + required: true + source_kind: + description: "Source kind" + required: false + default: workflow_dispatch + request_text: + description: "User request text" + required: false + default: "" + requested_by: + description: "GitHub login that requested the run" + required: false + workflow: + description: "Workflow file name" + required: false + default: "" + github_token: + description: "GitHub token for API access" + required: true + openai_api_key: + description: "OpenAI API key for Codex" + required: false + default: "" + claude_oauth_token: + description: "Claude Code OAuth token" + required: false + session_policy: + description: "Session continuity policy (none, track-only, resume-best-effort, resume-required)" + required: true + session_bundle_mode: + description: "Session bundle persistence mode (auto, always, never)" + required: false + default: auto + session_bundle_retention_days: + description: "Retention for uploaded session bundle artifacts" + required: false + default: "30" + session_fork_from_thread_key: + description: "Optional source thread key used to seed a new destination session when the destination has no session yet" + required: false + default: "" + memory_policy: + description: "Memory access policy JSON. Workflow callers can pass repository variables explicitly." + required: false + default: "" + memory_mode_override: + description: | + Explicit memory mode (enabled, read-only, disabled) that bypasses the policy. + Used by dedicated memory workflows so they always have memory on. + required: false + default: "" + memory_ref: + description: "Memory branch to clone when memory is enabled" + required: false + default: agent/memory + rubrics_policy: + description: "Rubrics access policy JSON. Empty defaults to read-only rubric steering." + required: false + default: "" + rubrics_mode_override: + description: | + Explicit rubrics mode (enabled, read-only, disabled) that bypasses the policy. + Used by dedicated rubrics workflows so they can write the rubrics branch. + required: false + default: "" + rubrics_ref: + description: "Rubrics branch to clone when rubrics are enabled" + required: false + default: agent/rubrics + rubrics_limit: + description: "Maximum selected rubrics to inject into the prompt" + required: false + default: "10" + +outputs: + response_file: + description: "Path to the response markdown file" + value: ${{ steps.run.outputs.response_file }} + session_log_file: + description: "Path to the session log JSONL file" + value: ${{ steps.run.outputs.session_log_file }} + raw_stdout_file: + description: "Path to raw acpx stdout captured on failure" + value: ${{ steps.run.outputs.raw_stdout_file }} + raw_stderr_file: + description: "Path to raw acpx stderr captured on failure" + value: ${{ steps.run.outputs.raw_stderr_file }} + session_name: + description: "acpx session name (if persistent)" + value: ${{ steps.run.outputs.session_name }} + acpx_record_id: + description: "acpx record ID" + value: ${{ steps.run.outputs.acpx_record_id }} + acpx_session_id: + description: "acpx session ID" + value: ${{ steps.run.outputs.acpx_session_id }} + thread_key: + description: "Thread key for session/state tracking" + value: ${{ steps.run.outputs.thread_key }} + prompt: + description: "Rendered prompt text" + value: ${{ steps.run.outputs.prompt }} + resume_status: + description: "Final acpx session continuity outcome" + value: ${{ steps.run.outputs.resume_status }} + last_resume_error: + description: "Session continuity error when resume failed" + value: ${{ steps.run.outputs.last_resume_error }} + session_bundle_restore_status: + description: "Result of restoring a prior session bundle artifact" + value: ${{ steps.run.outputs.session_bundle_restore_status }} + session_bundle_restore_error: + description: "Error emitted while restoring a prior session bundle artifact" + value: ${{ steps.run.outputs.session_bundle_restore_error }} + session_fork_from_thread_key: + description: "Source thread key used to seed this run, when a fork restore succeeded" + value: ${{ steps.run.outputs.session_fork_from_thread_key }} + session_fork_restore_status: + description: "Result of restoring the fork source bundle" + value: ${{ steps.run.outputs.session_fork_restore_status }} + session_fork_restore_error: + description: "Error emitted while restoring the fork source bundle" + value: ${{ steps.run.outputs.session_fork_restore_error }} + session_bundle_artifact_id: + description: "Uploaded session bundle artifact id" + value: ${{ steps.upload_session_bundle.outputs.artifact-id }} + session_bundle_artifact_name: + description: "Uploaded session bundle artifact name" + value: ${{ steps.bundle.outputs.artifact_name }} + memory_mode: + description: "Resolved memory mode (enabled, read-only, disabled)" + value: ${{ steps.memory_mode.outputs.mode }} + memory_available: + description: "Whether the agent memory branch was cloned successfully" + value: ${{ steps.memory.outputs.memory_available }} + memory_dir: + description: "Path to the downloaded agent memory checkout" + value: ${{ steps.memory.outputs.memory_dir }} + memory_committed: + description: "Whether the agent produced memory edits that were committed and pushed" + value: ${{ steps.commit_memory.outputs.committed }} + rubrics_mode: + description: "Resolved rubrics mode (enabled, read-only, disabled)" + value: ${{ steps.rubrics_mode.outputs.mode }} + rubrics_available: + description: "Whether the agent rubrics branch was cloned successfully" + value: ${{ steps.rubrics.outputs.rubrics_available }} + rubrics_dir: + description: "Path to the downloaded agent rubrics checkout" + value: ${{ steps.rubrics.outputs.rubrics_dir }} + rubrics_selected_count: + description: "How many rubrics were selected for this run" + value: ${{ steps.select_rubrics.outputs.selected_count }} + rubrics_committed: + description: "Whether the agent produced rubric edits that were committed and pushed" + value: ${{ steps.commit_rubrics.outputs.committed }} + +runs: + using: composite + steps: + - name: Verify built runtime + shell: bash + run: | + if [ ! -f .agent/dist/run.js ]; then + echo "Built runtime not found at .agent/dist/run.js" >&2 + echo "Run the setup-agent-runtime action before run-agent-task." >&2 + exit 1 + fi + + - name: Restore session bundle + id: restore + continue-on-error: true + shell: bash + env: + GH_TOKEN: ${{ inputs.github_token }} + GITHUB_TOKEN: ${{ inputs.github_token }} + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + ROUTE: ${{ inputs.route }} + LANE: ${{ inputs.lane }} + SESSION_POLICY: ${{ inputs.session_policy }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode }} + SESSION_FORK_FROM_THREAD_KEY: ${{ inputs.session_fork_from_thread_key }} + TARGET_KIND: ${{ inputs.target_kind }} + TARGET_NUMBER: ${{ inputs.target_number }} + run: node .agent/dist/cli/session-restore.js + + - name: Resolve memory mode + id: memory_mode + shell: bash + env: + AGENT_MEMORY_POLICY: ${{ inputs.memory_policy }} + MEMORY_MODE_OVERRIDE: ${{ inputs.memory_mode_override }} + ROUTE: ${{ inputs.route }} + run: node .agent/dist/cli/memory/resolve-policy.js + + - name: Set up agent memory + if: ${{ steps.memory_mode.outputs.read_enabled == 'true' }} + id: memory + uses: ./.github/actions/download-agent-memory + with: + github_token: ${{ inputs.github_token }} + ref: ${{ inputs.memory_ref }} + bootstrap_if_missing: ${{ inputs.memory_mode_override == 'enabled' && 'true' || 'false' }} + + - name: Resolve rubrics mode + id: rubrics_mode + shell: bash + env: + AGENT_RUBRICS_POLICY: ${{ inputs.rubrics_policy }} + RUBRICS_MODE_OVERRIDE: ${{ inputs.rubrics_mode_override }} + ROUTE: ${{ inputs.route }} + run: node .agent/dist/cli/rubrics/resolve-policy.js + + - name: Set up agent rubrics + if: ${{ steps.rubrics_mode.outputs.read_enabled == 'true' }} + id: rubrics + uses: ./.github/actions/download-agent-rubrics + with: + github_token: ${{ inputs.github_token }} + ref: ${{ inputs.rubrics_ref }} + bootstrap_if_missing: ${{ inputs.route == 'rubrics-initialization' && inputs.rubrics_mode_override == 'enabled' && 'true' || 'false' }} + + - name: Select applicable rubrics + if: ${{ steps.rubrics.outputs.rubrics_available == 'true' && steps.rubrics.outputs.rubrics_dir != '' }} + id: select_rubrics + continue-on-error: true + shell: bash + env: + REQUEST_TEXT: ${{ inputs.request_text }} + ROUTE: ${{ inputs.route }} + RUBRICS_CONTEXT_FILE: ${{ runner.temp }}/selected-rubrics.md + RUBRICS_DIR: ${{ steps.rubrics.outputs.rubrics_dir }} + RUBRICS_LIMIT: ${{ inputs.route == 'rubrics-review' && 'all' || inputs.rubrics_limit }} + RUBRICS_SELECT_ALL_ROUTES: ${{ inputs.route == 'rubrics-review' && 'true' || 'false' }} + RUBRICS_SELECT_DOMAINS: ${{ inputs.route == 'answer' && 'communication' || '' }} + run: | + all_route_args=() + if [ "${RUBRICS_SELECT_ALL_ROUTES}" = "true" ]; then + all_route_args+=(--all-routes) + fi + + node .agent/dist/cli/rubrics/select.js \ + --dir "${RUBRICS_DIR}" \ + --route "${ROUTE}" \ + --query "${REQUEST_TEXT}" \ + --best-effort \ + "${all_route_args[@]}" \ + --domains "${RUBRICS_SELECT_DOMAINS}" \ + --limit "${RUBRICS_LIMIT}" \ + --output-file "${RUBRICS_CONTEXT_FILE}" + + - name: Run agent task + id: run + shell: bash + env: + ACPX_AGENT: ${{ inputs.agent }} + ACPX_PERMISSION_MODE: ${{ inputs.permission_mode }} + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + INPUT_OPENAI_API_KEY: ${{ inputs.openai_api_key }} + CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude_oauth_token }} + MEMORY_AVAILABLE: ${{ steps.memory.outputs.memory_available }} + MEMORY_DIR: ${{ steps.memory.outputs.memory_dir }} + MEMORY_REF: ${{ steps.memory.outputs.memory_ref }} + RUBRICS_AVAILABLE: ${{ steps.rubrics.outputs.rubrics_available }} + RUBRICS_DIR: ${{ steps.rubrics.outputs.rubrics_dir }} + RUBRICS_REF: ${{ steps.rubrics.outputs.rubrics_ref }} + RUBRICS_CONTEXT_FILE: ${{ steps.select_rubrics.outputs.context_file }} + MODEL_REASONING_EFFORT: ${{ inputs.reasoning_effort }} + PROMPT_NAME: ${{ inputs.prompt }} + REPO_SLUG: ${{ github.repository }} + REQUEST_TEXT: ${{ inputs.request_text }} + REQUESTED_BY: ${{ inputs.requested_by }} + ROUTE: ${{ inputs.route }} + LANE: ${{ inputs.lane }} + SESSION_POLICY: ${{ inputs.session_policy }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode }} + SESSION_BUNDLE_RESTORE_STATUS: ${{ steps.restore.outputs.restore_status }} + SESSION_BUNDLE_RESTORE_ERROR: ${{ steps.restore.outputs.restore_error }} + SESSION_FORK_FROM_THREAD_KEY: ${{ steps.restore.outputs.fork_from_thread_key }} + SESSION_FORK_ACPX_SESSION_ID: ${{ steps.restore.outputs.fork_acpx_session_id }} + SESSION_FORK_RESTORE_STATUS: ${{ steps.restore.outputs.fork_restore_status }} + SESSION_FORK_RESTORE_ERROR: ${{ steps.restore.outputs.fork_restore_error }} + SKILL_NAME: ${{ inputs.skill }} + SKILL_ROOT: ${{ inputs.skill_root }} + SOURCE_KIND: ${{ inputs.source_kind }} + TARGET_KIND: ${{ inputs.target_kind }} + TARGET_NUMBER: ${{ inputs.target_number }} + TARGET_URL: ${{ inputs.target_url }} + WORKFLOW: ${{ inputs.workflow }} + run: | + # Keep the composite action alive long enough to run best-effort + # post-processing, then rethrow the agent exit code in a final step. + set +e + node .agent/dist/run.js + exit_code=$? + echo "exit_code=${exit_code}" >> "$GITHUB_OUTPUT" + exit 0 + + - name: Commit memory edits + if: >- + steps.run.outputs.exit_code == '0' && + steps.memory_mode.outputs.write_enabled == 'true' && + steps.memory.outputs.memory_available == 'true' && + steps.memory.outputs.memory_dir != '' + id: commit_memory + continue-on-error: true + shell: bash + env: + BRANCH: ${{ inputs.memory_ref }} + COMMIT_CWD: ${{ steps.memory.outputs.memory_dir }} + COMMIT_MESSAGE: "chore(memory): agent updates" + GH_TOKEN: ${{ inputs.github_token }} + GITHUB_REPOSITORY: ${{ github.repository }} + SET_UPSTREAM: "true" + run: node ${{ github.workspace }}/.agent/dist/cli/commit.js + + - name: Report memory commit failure + if: always() && steps.commit_memory.outcome == 'failure' + shell: bash + env: + MEMORY_REF: ${{ inputs.memory_ref }} + ROUTE: ${{ inputs.route }} + run: | + echo "::warning title=Memory commit failed::Failed to persist memory updates for route '${ROUTE}' to '${MEMORY_REF}'. Check the 'Commit memory edits' step for the push error." + + - name: Validate rubric edits + if: >- + steps.run.outputs.exit_code == '0' && + steps.rubrics_mode.outputs.write_enabled == 'true' && + steps.rubrics.outputs.rubrics_available == 'true' && + steps.rubrics.outputs.rubrics_dir != '' + id: validate_rubrics + shell: bash + run: node .agent/dist/cli/rubrics/validate.js --dir "${{ steps.rubrics.outputs.rubrics_dir }}" + + - name: Report rubrics validation failure + if: always() && steps.validate_rubrics.outcome == 'failure' + shell: bash + env: + RUBRICS_REF: ${{ inputs.rubrics_ref }} + ROUTE: ${{ inputs.route }} + run: | + echo "::warning title=Rubrics validation failed::Rubric edits for route '${ROUTE}' failed validation and were not committed to '${RUBRICS_REF}'. Check the 'Validate rubric edits' step for schema errors." + + - name: Commit rubric edits + if: >- + steps.run.outputs.exit_code == '0' && + steps.rubrics_mode.outputs.write_enabled == 'true' && + steps.rubrics.outputs.rubrics_available == 'true' && + steps.rubrics.outputs.rubrics_dir != '' && + steps.validate_rubrics.outcome == 'success' + id: commit_rubrics + continue-on-error: true + shell: bash + env: + BRANCH: ${{ inputs.rubrics_ref }} + COMMIT_CWD: ${{ steps.rubrics.outputs.rubrics_dir }} + COMMIT_MESSAGE: "chore(rubrics): agent updates" + GH_TOKEN: ${{ inputs.github_token }} + GITHUB_REPOSITORY: ${{ github.repository }} + SET_UPSTREAM: "true" + run: node ${{ github.workspace }}/.agent/dist/cli/commit.js + + - name: Report rubrics commit failure + if: always() && steps.commit_rubrics.outcome == 'failure' + shell: bash + env: + RUBRICS_REF: ${{ inputs.rubrics_ref }} + ROUTE: ${{ inputs.route }} + run: | + echo "::warning title=Rubrics commit failed::Failed to persist rubric updates for route '${ROUTE}' to '${RUBRICS_REF}'. Check the 'Commit rubric edits' step for the push error." + + - name: Require rubric initialization commit + if: always() && inputs.route == 'rubrics-initialization' && steps.run.outputs.exit_code == '0' + shell: bash + env: + COMMIT_OUTCOME: ${{ steps.commit_rubrics.outcome }} + RUBRICS_COMMITTED: ${{ steps.commit_rubrics.outputs.committed }} + RUBRICS_REF: ${{ inputs.rubrics_ref }} + run: | + if [ "$COMMIT_OUTCOME" != "success" ] || [ "$RUBRICS_COMMITTED" != "true" ]; then + echo "Rubrics initialization did not persist ${RUBRICS_REF}; failing first-run setup." >&2 + exit 1 + fi + + - name: Prepare session bundle + if: always() && steps.run.outputs.exit_code == '0' + id: bundle + continue-on-error: true + shell: bash + env: + ACPX_AGENT: ${{ inputs.agent }} + ACPX_RECORD_ID: ${{ steps.run.outputs.acpx_record_id }} + ACPX_SESSION_ID: ${{ steps.run.outputs.acpx_session_id }} + GITHUB_REPOSITORY: ${{ github.repository }} + LANE: ${{ inputs.lane }} + ROUTE: ${{ inputs.route }} + SESSION_POLICY: ${{ inputs.session_policy }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode }} + TARGET_KIND: ${{ inputs.target_kind }} + TARGET_NUMBER: ${{ inputs.target_number }} + run: node .agent/dist/cli/session-backup.js + + - name: Upload session bundle artifact + if: always() && steps.run.outputs.exit_code == '0' && steps.bundle.outputs.bundle_created == 'true' + id: upload_session_bundle + continue-on-error: true + uses: actions/upload-artifact@v4 + with: + name: ${{ steps.bundle.outputs.artifact_name }} + path: ${{ steps.bundle.outputs.bundle_file }} + retention-days: ${{ inputs.session_bundle_retention_days }} + + - name: Register session bundle artifact + if: always() && steps.run.outputs.exit_code == '0' && steps.upload_session_bundle.outputs.artifact-id != '' + id: register_session_bundle + continue-on-error: true + shell: bash + env: + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + LANE: ${{ inputs.lane }} + ROUTE: ${{ inputs.route }} + SESSION_POLICY: ${{ inputs.session_policy }} + SESSION_BUNDLE_ARTIFACT_ID: ${{ steps.upload_session_bundle.outputs.artifact-id }} + SESSION_BUNDLE_ARTIFACT_NAME: ${{ steps.bundle.outputs.artifact_name }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode }} + SESSION_RECORD_ID: ${{ steps.run.outputs.acpx_record_id }} + SESSION_ID: ${{ steps.run.outputs.acpx_session_id }} + TARGET_KIND: ${{ inputs.target_kind }} + TARGET_NUMBER: ${{ inputs.target_number }} + run: node .agent/dist/cli/session-register.js + + - name: Propagate agent exit code + if: steps.run.outputs.exit_code != '0' + shell: bash + run: exit "${{ steps.run.outputs.exit_code }}" diff --git a/.github/actions/run-skill-setup/action.yml b/.github/actions/run-skill-setup/action.yml new file mode 100644 index 0000000..7c45294 --- /dev/null +++ b/.github/actions/run-skill-setup/action.yml @@ -0,0 +1,112 @@ +name: Run Skill Setup +description: Run the optional setup.sh hook for a repository skill. + +inputs: + skill: + description: "User-defined skill name" + required: true + skill_root: + description: "Root directory for user-defined skills" + required: false + default: ".skills" + trusted_ref: + description: "Whether setup is loaded from a trusted checkout" + required: true + run_setup: + description: "Whether to run setup.sh when it exists" + required: false + default: "true" + +outputs: + exists: + description: "Whether the skill has a SKILL.md file" + value: ${{ steps.setup.outputs.exists }} + skill_path: + description: "Repository-relative SKILL.md path" + value: ${{ steps.setup.outputs.skill_path }} + setup_exists: + description: "Whether the skill has a setup.sh script" + value: ${{ steps.setup.outputs.setup_exists }} + setup_ran: + description: "Whether setup.sh ran" + value: ${{ steps.setup.outputs.setup_ran }} + setup_path: + description: "Repository-relative setup.sh path" + value: ${{ steps.setup.outputs.setup_path }} + +runs: + using: composite + steps: + - name: Run skill setup + id: setup + shell: bash + env: + SKILL_NAME: ${{ inputs.skill }} + SKILL_ROOT: ${{ inputs.skill_root }} + SKILL_SETUP_TRUSTED_REF: ${{ inputs.trusted_ref }} + RUN_SKILL_SETUP: ${{ inputs.run_setup }} + run: | + set -euo pipefail + + skill="${SKILL_NAME}" + skill_root="${SKILL_ROOT:-.skills}" + if [ -z "$skill_root" ]; then + skill_root=".skills" + fi + + if [[ ! "$skill" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then + printf 'Invalid skill name "%s". Use letters, numbers, dots, underscores, or hyphens.\n' "$skill" >&2 + exit 2 + fi + case "$skill_root" in + /*|..|../*|*/..|*/../*) + printf 'Skill root must stay inside the repository: %s\n' "$skill_root" >&2 + exit 2 + ;; + esac + skill_root="${skill_root%/}" + + skill_root_dir="$GITHUB_WORKSPACE/$skill_root" + skill_dir="$skill_root_dir/$skill" + skill_file="$skill_dir/SKILL.md" + setup_file="$skill_dir/setup.sh" + skill_path="$skill_root/$skill/SKILL.md" + setup_path="$skill_root/$skill/setup.sh" + + { + printf 'skill_path=%s\n' "$skill_path" + printf 'setup_path=%s\n' "$setup_path" + printf 'setup_ran=false\n' + } >> "$GITHUB_OUTPUT" + + if [ ! -f "$skill_file" ]; then + printf 'exists=false\n' >> "$GITHUB_OUTPUT" + printf 'setup_exists=false\n' >> "$GITHUB_OUTPUT" + printf 'Skill file not found: %s\n' "$skill_path" + exit 0 + fi + printf 'exists=true\n' >> "$GITHUB_OUTPUT" + + if [ ! -f "$setup_file" ]; then + printf 'setup_exists=false\n' >> "$GITHUB_OUTPUT" + printf 'No skill setup script found: %s\n' "$setup_path" + exit 0 + fi + printf 'setup_exists=true\n' >> "$GITHUB_OUTPUT" + + if [ "$RUN_SKILL_SETUP" != "true" ]; then + printf 'Skill setup script found: %s\n' "$setup_path" + exit 0 + fi + + if [ "$SKILL_SETUP_TRUSTED_REF" != "true" ]; then + printf 'Refusing to run %s from an untrusted PR checkout\n' "$setup_path" >&2 + exit 1 + fi + + export SKILL_NAME="$skill" + export SKILL_ROOT="$skill_root_dir" + export SKILL_DIR="$skill_dir" + bash "$setup_file" + printf 'setup_ran=true\n' >> "$GITHUB_OUTPUT" + printf 'Skill setup completed: %s\n' "$setup_path" diff --git a/.github/actions/scheduled-activity-gate/action.yml b/.github/actions/scheduled-activity-gate/action.yml new file mode 100644 index 0000000..ac4e41f --- /dev/null +++ b/.github/actions/scheduled-activity-gate/action.yml @@ -0,0 +1,70 @@ +name: Scheduled Activity Gate +description: Resolve scheduled workflow policy and skip when declared activity has not advanced. Runs before the TypeScript runtime is built. + +inputs: + github_token: + description: "GitHub token used to fetch cursor refs" + required: true + schedule_policy: + description: "AGENT_SCHEDULE_POLICY JSON" + required: false + default: "" + workflow: + description: "Workflow filename, for example agent-memory-scan.yml" + required: true + dependency_ref: + description: "Ref containing dependency state.json" + required: false + default: "" + dependency_field: + description: "Field in dependency state.json that contains an ISO timestamp" + required: false + default: "" + self_ref: + description: "Ref containing this workflow state.json" + required: false + default: "" + self_field: + description: "Field in this workflow state.json that contains an ISO timestamp" + required: false + default: "" + activity_count: + description: "Optional count of relevant activity for event-count based gates" + required: false + default: "" + +outputs: + skip: + description: "true when the scheduled workflow should skip expensive work" + value: ${{ steps.resolve.outputs.skip }} + mode: + description: "Resolved schedule mode" + value: ${{ steps.resolve.outputs.mode }} + reason: + description: "Human-readable gate decision reason" + value: ${{ steps.resolve.outputs.reason }} + dependency_value: + description: "Resolved dependency cursor value" + value: ${{ steps.resolve.outputs.dependency_value }} + self_value: + description: "Resolved self cursor value" + value: ${{ steps.resolve.outputs.self_value }} + +runs: + using: composite + steps: + - name: Resolve scheduled activity gate + id: resolve + shell: bash + env: + AGENT_SCHEDULE_POLICY: ${{ inputs.schedule_policy }} + ACTIVITY_COUNT: ${{ inputs.activity_count }} + DEPENDENCY_FIELD: ${{ inputs.dependency_field }} + DEPENDENCY_REF: ${{ inputs.dependency_ref }} + GH_TOKEN: ${{ inputs.github_token }} + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ inputs.github_token }} + SELF_FIELD: ${{ inputs.self_field }} + SELF_REF: ${{ inputs.self_ref }} + WORKFLOW_FILENAME: ${{ inputs.workflow }} + run: bash "${GITHUB_WORKSPACE}/.agent/scripts/resolve-scheduled-activity-gate.sh" diff --git a/.github/actions/setup-agent-runtime/action.yml b/.github/actions/setup-agent-runtime/action.yml new file mode 100644 index 0000000..c802087 --- /dev/null +++ b/.github/actions/setup-agent-runtime/action.yml @@ -0,0 +1,140 @@ +name: Setup Agent Runtime +description: | + Check out-independent runtime bootstrap for the Sepo agent. + Reuses preinstalled Node.js on self-hosted runners, installs Node.js on + GitHub-hosted runners, then builds the TypeScript runtime in place and + optionally installs missing agent CLIs. + +inputs: + node_version: + description: Node.js version to install. + required: false + default: "22" + install_codex: + description: Whether to install the Codex CLI when missing. + required: false + default: "false" + codex_version: + description: Optional @openai/codex version to install when the CLI is missing. + required: false + default: "" + install_claude: + description: Whether to install the Claude CLI when missing. + required: false + default: "false" + claude_version: + description: Optional Claude Code version to install when the CLI is missing. + required: false + default: "" + +runs: + using: composite + steps: + - name: Ensure Node.js available on GitHub-hosted runners + if: ${{ runner.environment != 'self-hosted' }} + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: ${{ inputs.node_version }} + + - name: Verify preinstalled Node.js on self-hosted runners + if: ${{ runner.environment == 'self-hosted' }} + shell: bash + env: + REQUESTED_NODE_VERSION: ${{ inputs.node_version }} + run: | + set -euo pipefail + + missing=() + for cmd in node npm; do + if ! command -v "$cmd" >/dev/null 2>&1; then + missing+=("$cmd") + fi + done + + if [ "${#missing[@]}" -ne 0 ]; then + echo "Self-hosted runner is missing required Node.js tools: ${missing[*]}" >&2 + echo "Install a compatible Node.js runtime on the runner or switch to a GitHub-hosted runner." >&2 + exit 1 + fi + + installed_node="$(node -p 'process.versions.node')" + installed_npm="$(npm --version)" + requested_major="$(printf '%s' "$REQUESTED_NODE_VERSION" | sed -nE 's/^v?([0-9]+).*/\1/p')" + installed_major="${installed_node%%.*}" + + if [ -n "$requested_major" ] && [ "$installed_major" != "$requested_major" ]; then + echo "Self-hosted runner has Node.js ${installed_node}, but setup-agent-runtime requires major version ${requested_major}.x." >&2 + exit 1 + fi + + echo "Using preinstalled Node.js ${installed_node} and npm ${installed_npm} on self-hosted runner." + + - name: Add runtime tool bins to PATH + shell: bash + run: | + echo "$GITHUB_WORKSPACE/.agent/node_modules/.bin" >> "$GITHUB_PATH" + echo "$HOME/.local/bin" >> "$GITHUB_PATH" + echo "NODE_PATH=$GITHUB_WORKSPACE/.agent/node_modules${NODE_PATH:+:$NODE_PATH}" >> "$GITHUB_ENV" + + - name: Install runtime dependencies + shell: bash + working-directory: .agent + run: npm ci + + - name: Build runtime + shell: bash + working-directory: .agent + run: npm run build + + - name: Verify base runner tools + shell: bash + run: | + missing=() + for cmd in git gh jq bash; do + if ! command -v "$cmd" >/dev/null 2>&1; then + missing+=("$cmd") + fi + done + + if [ "${#missing[@]}" -ne 0 ]; then + echo "Missing required runner tools: ${missing[*]}" >&2 + exit 1 + fi + + - name: Install Codex CLI + if: ${{ inputs.install_codex == 'true' }} + shell: bash + env: + CODEX_VERSION: ${{ inputs.codex_version }} + run: | + if command -v codex >/dev/null 2>&1; then + echo "Codex CLI already available." + exit 0 + fi + + pkg="@openai/codex" + if [ -n "$CODEX_VERSION" ]; then + pkg="$pkg@$CODEX_VERSION" + fi + + npm install -g "$pkg" + echo "$(npm prefix -g)/bin" >> "$GITHUB_PATH" + + - name: Install Claude CLI + if: ${{ inputs.install_claude == 'true' }} + shell: bash + env: + CLAUDE_VERSION: ${{ inputs.claude_version }} + run: | + if command -v claude >/dev/null 2>&1; then + echo "Claude CLI already available." + exit 0 + fi + + if [ -n "$CLAUDE_VERSION" ]; then + curl -fsSL https://claude.ai/install.sh | bash -s -- "$CLAUDE_VERSION" + else + curl -fsSL https://claude.ai/install.sh | bash + fi + + echo "$HOME/.local/bin" >> "$GITHUB_PATH" diff --git a/.github/prompts/_base.md b/.github/prompts/_base.md new file mode 100644 index 0000000..fb31799 --- /dev/null +++ b/.github/prompts/_base.md @@ -0,0 +1,26 @@ +You are the Sepo agent running in a GitHub Actions workflow on the `${REPO_SLUG}` repository. + +## Context + +Repository: `${REPO_SLUG}` +Target: ${TARGET_KIND} #${TARGET_NUMBER} +Source: ${SOURCE_KIND} +URL: ${TARGET_URL} +Requested by: ${REQUESTED_BY} +Request: ${REQUEST_TEXT} + +## General guidelines + +- Before starting, check for broader project context: + - Read the target for references to parent issues, tracking issues, or project plans (e.g., "Parent: #24", "Part of #24"). + - If the target or its linked issues reference a broader plan or discussion, read those with `gh issue view` or `gh api` to understand the goals, constraints, and phasing. Evaluate the task against that context, not just in isolation. +- Tools like `gh`, `git` can help you gather the needed context: + - `gh issue view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,labels,state,url` for issues + - `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,files,labels,reviews,reviewDecision,state,url` and `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` for PRs + - For discussions: `node .agent/dist/cli/fetch-discussion-transcript.js ${TARGET_NUMBER}` + - Use the local checkout and repository files as the primary source of truth for the current code state + - Avoid broad searches through generated/vendor directories like `.git/`, `node_modules/`, `.agent/node_modules/`, `dist/`, and `.agent/dist/` unless the task is specifically about them +- Since you are running inside a github action, there are a few other differences compared to directly interacting with users: + - You have full permission to run commands given it's a sandbox environment. + - When you draft a message and when you want to refer to files, please use links for github files rather than local file references. + - Do not run destructive cleanup commands as there are followup steps that handle this. diff --git a/.github/prompts/_memory.md b/.github/prompts/_memory.md new file mode 100644 index 0000000..0b0e9d2 --- /dev/null +++ b/.github/prompts/_memory.md @@ -0,0 +1,31 @@ +## Repository memory + +`${MEMORY_DIR}` is a read-and-write checkout of the dedicated `${MEMORY_REF}` branch. It is the durable memory surface the agent composes across runs. + +Layout: +- `${MEMORY_DIR}/PROJECT.md` — slow-changing project context: goals, constraints, open questions +- `${MEMORY_DIR}/MEMORY.md` — durable learned conventions and lessons +- `${MEMORY_DIR}/daily/YYYY-MM-DD.md` — append-only daily bullets +- `${MEMORY_DIR}/github///*.json` — a deterministic mirror of repo history (`issue-*.json`, `pull-*.json`, `discussion-*.json`) +- These are the seeded anchor files, not an exhaustive schema; the memory tree may also contain additional agent-created notes when that helps organize durable context. + +Reading memory: +- Treat `${MEMORY_DIR}` as the memory root. Pull context in this order: `PROJECT.md`, `MEMORY.md`, relevant `daily/YYYY-MM-DD.md` files, then `github///*.json` artifacts or `memory/search.js` results. +- `daily/` is date-partitioned. Read the newest files first when you need recent activity or recent curation context. +- `github/` is a repo-namespaced, type-prefixed mirror. When you know the target repository and number, go straight to the likely file: `github///issue-.json`, `github///pull-.json`, `github///discussion-.json`, or related linked artifact numbers. +- Cite mirrored artifacts in notes with backlink-style paths such as `[[github///issue-.json]]`. +- Use `node .agent/dist/cli/memory/search.js --dir "${MEMORY_DIR}" ""` for broader lookup across both markdown and JSON when the right file is not obvious. + +Writing memory: +- For standard bullet edits, prefer `memory/update.js` so formatting, dedup, and section placement stay consistent. +- Add a durable entry: `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file MEMORY.md --section Durable ""` +- Add a project note: `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file PROJECT.md --section "Open Questions" ""` +- Append a daily bullet: `node .agent/dist/cli/memory/update.js daily-append --dir "${MEMORY_DIR}" ""` +- Replace or remove an entry: `... replace --file MEMORY.md --section Durable --match "" --with ""` / `... remove --file MEMORY.md --section Durable --match ""` +- If the CLI shape does not fit, you may edit repo-local memory files under `${MEMORY_DIR}` directly with normal tools. Keep the existing layout coherent and stay within the memory tree. + +Rules of thumb: +- Treat memory as advisory context. If memory disagrees with the live repo or GitHub state, trust the live state and update memory to match. +- Keep bullets terse (under ~140 chars). Do not mirror obvious PR metadata into `MEMORY.md` — the `github/` mirror already covers that. +- Only write durable memory when a fact is stable enough to outlast the current task. Most tasks produce zero `MEMORY.md` edits. +- The workflow commits any changes you make under `${MEMORY_DIR}` and pushes them to `${MEMORY_REF}`. Do not `git commit` inside `${MEMORY_DIR}` yourself. diff --git a/.github/prompts/_rubrics.md b/.github/prompts/_rubrics.md new file mode 100644 index 0000000..8c9a501 --- /dev/null +++ b/.github/prompts/_rubrics.md @@ -0,0 +1,17 @@ +## User/team rubrics + +Rubrics are user/team-owned preferences for how agent work should be implemented, reviewed, and communicated. They are separate from repository memory: memory captures agent/project continuity, while rubrics capture what users want the agent to optimize for and be evaluated against. + +`${RUBRICS_DIR}` is a checkout of the dedicated `${RUBRICS_REF}` branch. The selected rubrics below were retrieved for this route and request as a starting shortlist, not as the complete rubric set. + +You may browse `${RUBRICS_DIR}` for additional active user/team rubrics when the selected shortlist looks incomplete for the task. Prefer route-applicable rubrics, and for answer-only work prefer communication rubrics. + +Use rubrics as normative guidance: +- During implementation or PR fixes, satisfy applicable rubrics when they fit the request and repository state. +- During review, inspect additional review or coding rubrics when needed, then evaluate whether the proposed implementation satisfies applicable rubrics and cite concrete evidence. +- If a selected rubric clearly does not apply, ignore it briefly rather than overfitting the task. +- Do not edit rubrics during normal implementation/review runs; only Agent / Rubrics / Initialization and Agent / Rubrics / Update should change the rubrics branch. + +Selected rubrics: + +${RUBRICS_CONTEXT} diff --git a/.github/prompts/agent-answer.md b/.github/prompts/agent-answer.md new file mode 100644 index 0000000..e66d9da --- /dev/null +++ b/.github/prompts/agent-answer.md @@ -0,0 +1,20 @@ +## Task Description + +Your task is to directly respond to the following user's mention: + +${MENTION_BODY} + +Instructions: +- Answer the user's question directly, or explain the limitation if the routed request is unsupported. +- You may use `gh` and repository files to gather context, but do not post comments directly via `gh` or any other GitHub write API. +- When the user asks for planning/procedure guidance, remain in answer-only mode and return a plan-only response (do not start implementation): + 1. Explore the relevant codebase with repository inspection tools and cite concrete files. + 2. Summarize the existing architecture and patterns tied to the request. + 3. Propose an implementation approach aligned to those patterns. + 4. Present a clear step-by-step execution plan and ask for approval before coding. + 5. Ask focused clarification questions only when blockers remain. +- For planning responses, prioritize concrete process/procedure over generic product-spec sections unless the user asks for a spec format. +- Return only the reply body as your final output; the workflow will post it on the original surface. +- Keep the response concise and actionable. +- Format as GitHub-flavored markdown. +- Do not add a top-level title. diff --git a/.github/prompts/agent-create-action.md b/.github/prompts/agent-create-action.md new file mode 100644 index 0000000..c069aea --- /dev/null +++ b/.github/prompts/agent-create-action.md @@ -0,0 +1,64 @@ +## Task Description + +The user asked the agent to create a recurring or durable automation. + +Your task is to open a normal implementation PR that adds or updates one native GitHub Actions workflow under `.github/workflows/`. Do **not** create `.agent/actions/*` specs, a generic scheduler, or new runtime infrastructure. + +## Scheduled Workflow Contract + +Use GitHub Actions as the scheduler and activation mechanism: + +- Start from `.agent/action-templates/agent-action-template.yml`, copy it to `.github/workflows/agent-action-.yml`, and replace every placeholder. +- Include `workflow_dispatch` for manual test runs. +- Include `schedule` only when the requested automation should run automatically. +- Use the existing shared actions from the template: `resolve-github-auth`, `resolve-agent-provider`, `check-agent-action-expiration`, `setup-agent-runtime`, and `run-agent-task`. +- Keep the workflow scoped with least-privilege GitHub permissions; add issue write permission only when enabling issue reporting. +- Set a unique `lane` such as `agent-action-` so scheduled runs do not share session identity with normal answer traffic. +- Set `permission_mode: approve-all`, `memory_mode_override: read-only`, and `session_policy: track-only` for the scheduled agent task so recurring runs stay one-shot, write run metadata, and do not write repository memory or resume interactive sessions. +- Prefer `prompt: answer` and `route: answer`; put the bounded recurring task in `request_text`. +- If the workflow should report to an issue, set `REPORT_ISSUE_NUMBER`, add `issues: write`, and post `steps.agent.outputs.response_file` to that issue after the agent run. + +## Expiration Guard + +GitHub Actions does not expire scheduled workflows automatically. Every generated scheduled workflow must use the shared expiration action before provider/runtime setup and before the agent run: + +```yaml +- name: Check expiration + id: expiration + uses: ./.github/actions/check-agent-action-expiration + with: + expires_at: ${{ env.ACTION_EXPIRES_AT }} +``` + +Gate all expensive/provider-backed steps with: + +```yaml +if: steps.expiration.outputs.expired != 'true' +``` + +Use a simple static expiration date unless the user specifies one. If unspecified, choose a short default such as 30 days from the current date and mention it in the PR body. + +Do not add automatic extension or cleanup logic in the first generated workflow unless the user explicitly asked for lifecycle automation. Extending or removing an expired workflow should happen through normal PR review. + +## Instructions + +1. Read the issue and linked context with `gh`. +2. Inspect `.github/workflows/` for an existing generated workflow that should be updated instead of adding a duplicate. +3. Copy `.agent/action-templates/agent-action-template.yml` to the generated workflow path and fill in the workflow name, cron, expiration, lane, request text, and optional reporting target. Add `issues: write` only when setting `REPORT_ISSUE_NUMBER` for issue reporting. +4. Add or update exactly one standalone workflow unless the request clearly requires more. +5. Keep the recurring task bounded: describe what to check, allowed side effects, expiration, and where to report. +6. Do not add custom scheduler code, `.agent/actions` specs, or a new `run-action` route. +7. Run focused validation, at minimum YAML parsing for the generated workflow and `cd .agent && npm test` when practical. + +## Response Format + +Return exactly one JSON object: + +```json +{ + "summary": "What scheduled workflow was added or changed, how it is triggered, and when it expires.", + "commit_message": "Add scheduled agent workflow", + "pr_title": "Add scheduled agent workflow", + "pr_body": "Summary, trigger schedule, expiration date, reporting behavior, validation, and issue-closing text when applicable." +} +``` diff --git a/.github/prompts/agent-dispatch.md b/.github/prompts/agent-dispatch.md new file mode 100644 index 0000000..97df1fe --- /dev/null +++ b/.github/prompts/agent-dispatch.md @@ -0,0 +1,48 @@ +## Task Description + +The user mentioned the agent on GitHub and your task is to infer user intention and triage to specific routes: + +The message that mentioned the agent: +${MENTION_BODY} + +## Instruction + +Choose exactly one route: +- `answer`: answer inline now +- `implement`: request approval to run the implementation workflow +- `fix-pr`: start the PR-fix workflow immediately; only valid for `pull_request` +- `review`: start the review workflow immediately; only valid for `pull_request` +- `orchestrate`: start the orchestrator workflow immediately; only valid for `issue` or `pull_request` +- `create-action`: request approval to create a scheduled GitHub Actions workflow for recurring agent automation +- `unsupported`: explain the limitation inline + +Return exactly one JSON object and nothing else: + +```json +{ + "route": "answer | implement | fix-pr | review | orchestrate | create-action | unsupported", + "needs_approval": true, + "summary": "One short sentence for the user describing what the agent will do next.", + "confidence": "low | medium | high", + "issue_title": "", + "issue_body": "" +} +``` + +Rules: +- Use `implement` when the user is explicitly asking the agent to make code changes. +- Use `fix-pr` when the user is explicitly asking the agent to update an existing PR to address review feedback or requested changes. +- Use `review` only when the user is explicitly asking for a PR review or another review pass. +- Use `orchestrate` when the user explicitly asks for orchestration, follow-up automation, or a bounded multi-step agent workflow on an issue or pull request. +- Use `create-action` when the user asks to create an automatically running or durable automation, monitor, scheduled job, or recurring check. +- Use `answer` for questions, clarification, lightweight analysis, or discussion. + - Sometimes the user may also ask the agent to review some code (and the user could be explicit about just review and launch a review agent). In this case, we should also resolve to `answer`. +- Use `unsupported` when the user asks for a workflow this repo does not support yet. +- `fix-pr` is only valid for `pull_request` targets. If the request is not on a pull request, use `unsupported`. +- `orchestrate` is only valid for `issue` and `pull_request` targets. If the request is on another target kind, use `unsupported`. +- Keep `summary` short and user-facing. +- When `route` is `implement` or `create-action`, always populate `issue_title` (concise, under 70 chars) + and `issue_body` (structured markdown with goal, acceptance criteria, and any + relevant context from the original message). These will be used to create a + tracking issue that the user can review and edit before approving. +- When `route` is not `implement` or `create-action`, leave `issue_title` and `issue_body` empty. diff --git a/.github/prompts/agent-fix-pr.md b/.github/prompts/agent-fix-pr.md new file mode 100644 index 0000000..90941f7 --- /dev/null +++ b/.github/prompts/agent-fix-pr.md @@ -0,0 +1,57 @@ +## Task Description + +Fix pull request #${TARGET_NUMBER} to address review feedback and requested changes. + +Trigger metadata: +- Triggering source kind: `${REQUEST_SOURCE_KIND}` +- Triggering comment/review ID: `${REQUEST_COMMENT_ID}` +- Triggering comment/review URL: `${REQUEST_COMMENT_URL}` +- Orchestrator handoff context, when this run was launched by automation: + `${ORCHESTRATOR_CONTEXT}` + +Instructions: +1. Work only on the existing PR branch. Do not create a new branch or a new PR. +2. Gather current PR context: + - `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,reviews,files,headRefOid,reviewDecision,state,url` + - `gh api --paginate repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/comments` + - `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` +3. If a triggering comment or review ID is present, fetch that exact request first: + - For issue_comment: `gh api repos/${REPO_SLUG}/issues/comments/${REQUEST_COMMENT_ID}` + - For pull_request_review_comment: `gh api repos/${REPO_SLUG}/pulls/comments/${REQUEST_COMMENT_ID}` + - For pull_request_review: `gh api repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/reviews/${REQUEST_COMMENT_ID}` +4. Before editing, identify the latest actionable request you are addressing. + Use this priority order and do not revive older feedback that appears fixed + or superseded: + 1. the exact triggering comment or review, when an ID is present; + 2. non-empty `${ORCHESTRATOR_CONTEXT}` from the orchestrator; treat it as + the selected fix-pr task and constraints, not just background context; + 3. the latest review synthesis and its action items; + 4. recent human maintainer comments; + 5. older reviews/comments only when still applicable to the current diff. +5. Treat INFO-level notes, explicitly optional suggestions, already-fixed + findings, and human-judgment nits as non-actionable unless the exact + trigger or handoff context explicitly asks you to handle them. +6. Address the selected PR feedback with the smallest complete change. If no + actionable branch change remains, leave the working tree unchanged and say + so clearly in the JSON summary. +7. Run lightweight, directly relevant checks when they are clearly applicable. +8. If a line-specific clarification is useful, you may post an inline PR comment + with `gh`, but do not post a top-level summary comment. +9. Do not commit. Leave changes in the working tree. + +Return exactly one JSON object and nothing else: + +```json +{ + "summary": "Concise GitHub-flavored markdown for the workflow logs and PR status comment.", + "commit_message": "Concise commit message under 72 characters." +} +``` + +Format rules: +- `summary` should use concise GitHub-flavored markdown. +- Use bullet points for the main outcomes in `summary`. +- When there is secondary detail, prefer `
......
` blocks inside `summary`. +- `commit_message` should describe the actual fix made, not just the PR number. +- If you cannot determine a better commit message from the work performed, return an empty string for `commit_message` so the workflow can fall back to its default commit message. +- Keep `summary` brief and avoid a preamble. diff --git a/.github/prompts/agent-implement-metadata.md b/.github/prompts/agent-implement-metadata.md new file mode 100644 index 0000000..5031804 --- /dev/null +++ b/.github/prompts/agent-implement-metadata.md @@ -0,0 +1,33 @@ +## Task Description + +An explicit `/implement` request on a pull request or discussion needs a tracking issue before implementation can run. + +Generate only the tracking issue metadata. The `/implement` command is already explicit approval to run implementation; do not decide or approve the route. + +## Context Gathering + +- Read the target context first: + - For pull requests, run `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,files,labels,reviews,reviewDecision,state,url`. + - For discussions, run `node .agent/dist/cli/fetch-discussion-transcript.js ${TARGET_NUMBER}`. +- Use the request text, target title/body, and recent relevant discussion to infer the implementation task. +- Do not derive the title by copying the literal text after `/implement`. +- Ignore earlier prose mentions of `/implement` unless they are part of the current user request context. + +Return exactly one JSON object and nothing else: + +```json +{ + "issue_title": "Concise implementation title under 70 characters", + "issue_body": "Structured markdown with goal, context, and acceptance criteria", + "base_pr": "Optional positive integer PR number for stacked implementation" +} +``` + +Rules: +- Make `issue_title` a context-derived task title, not a command tail. +- Keep `issue_title` under 70 characters. +- Include enough context in `issue_body` for the implementation workflow to act without rereading every comment. +- Omit `base_pr` unless `TARGET_KIND` is `pull_request` and the current user request explicitly asks for a stacked or follow-up PR. +- When setting `base_pr`, set it to the current target pull request number (`TARGET_NUMBER`) as digits only, with no `#` prefix. +- Do not infer `base_pr` from target title/body prose alone. +- If the task is ambiguous, describe the known request and the ambiguity in `issue_body`; still provide the best concise title. diff --git a/.github/prompts/agent-implement.md b/.github/prompts/agent-implement.md new file mode 100644 index 0000000..17f77c5 --- /dev/null +++ b/.github/prompts/agent-implement.md @@ -0,0 +1,30 @@ +## Task Description + +Implement GitHub issue #${TARGET_NUMBER}. + +Instructions: +1. Start by reading the current issue state with `gh issue view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,labels,state,url`. Please also check the broader project context. +2. Make the smallest complete change that resolves the issue. +3. Run lightweight, directly relevant checks when they are clearly applicable. +4. Do not commit. Leave changes in the working tree. + +Return exactly one JSON object and nothing else: + +```json +{ + "summary": "One short paragraph for the workflow logs and issue comment.", + "commit_message": "Concise commit message under 72 characters.", + "pr_title": "Concise pull request title under 72 characters.", + "pr_body": "GitHub-flavored markdown pull request body." +} +``` + +Rules: +- `summary` should briefly describe the code changes made and any verification run. +- `commit_message` should describe the actual code change, not just the issue number. +- `pr_title` should be specific to the actual change, not just the issue number. +- `pr_body` should be concise, clear, and ready to pass to `gh pr create --body-file`. +- If you cannot determine a better commit message from the work performed, return an empty string for `commit_message` so the workflow can fall back to its default commit message. +- When you return a non-empty `pr_body` for an issue-backed implementation like this one, include GitHub issue-closing text for the target issue, for example `Closes #${TARGET_NUMBER}`. +- Keep the issue-closing line in the PR body itself, not only in `summary`. +- If you cannot determine better PR metadata from the work performed, return empty strings for `pr_title` and `pr_body` so the workflow can fall back to its default PR title/body. diff --git a/.github/prompts/agent-issue-enhance.md b/.github/prompts/agent-issue-enhance.md new file mode 100644 index 0000000..f953ce2 --- /dev/null +++ b/.github/prompts/agent-issue-enhance.md @@ -0,0 +1,28 @@ +Instructions: +- Read the issue first with `gh issue view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,labels,state,url`. +- Gather repo context needed to make the issue more execution-ready: + - linked or related issues/PRs + - relevant docs, workflows, tests, and code paths + - ongoing work or constraints that should shape the implementation +- Treat this as a stronger, repo-aware issue-enrichment pass. +- Do not implement code and do not dispatch another workflow. +- Return an enrichment comment (as your final output) that helps the user confirm or refine the task before later implementation. +- Do not post comments directly via `gh`. +- Keep the response concise, but substantive enough to be actionable. +- Do not add a top-level title. + +Provide a response with these sections: +- `Goal / Bigger picture` +- `Related Context In Repo` +- `Constraints / Ongoing Work` +- `Proposed Acceptance Criteria` +- `Verification Plan` + +Style: +```text + +**Goal / Bigger picture:** + +**Related Context In Repo:** ... + +``` diff --git a/.github/prompts/agent-orchestrator.md b/.github/prompts/agent-orchestrator.md new file mode 100644 index 0000000..4af72de --- /dev/null +++ b/.github/prompts/agent-orchestrator.md @@ -0,0 +1,127 @@ +## Task Description + +You are the post-action orchestrator planner. Decide whether this automation +chain should stop or hand off to exactly one allowed next action. + +## Handoff Context + +- Source action: `${ORCHESTRATOR_SOURCE_ACTION}` +- Source conclusion: `${ORCHESTRATOR_SOURCE_CONCLUSION}` +- Source recommended next step: `${ORCHESTRATOR_SOURCE_RECOMMENDED_NEXT_STEP}` +- Source run ID: `${ORCHESTRATOR_SOURCE_RUN_ID}` +- Current round: `${ORCHESTRATOR_CURRENT_ROUND}` +- Max rounds: `${ORCHESTRATOR_MAX_ROUNDS}` +- Current target: `${TARGET_KIND} #${TARGET_NUMBER}` +- Next target from source action, if any: `${ORCHESTRATOR_NEXT_TARGET_NUMBER}` +- Source handoff context, if any: `${ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT}` +- Self-approval enabled: `${ORCHESTRATOR_SELF_APPROVE_ENABLED}` +- Self-merge enabled: `${ORCHESTRATOR_SELF_MERGE_ENABLED}` + +## Runtime Policy + +The runtime validates your decision after you return it. You cannot override +these policy rules: + +- Round budget must not be exceeded. +- `implement` may hand off to `review` only when implementation succeeded and + produced a pull request target. +- `review` may hand off to `agent-self-approve` when self-approval is enabled + and either the verdict is `SHIP` or the source recommended next step is + `HUMAN_DECISION`. +- `review` may hand off to `fix-pr` only for `MINOR_ISSUES`, + `NEEDS_REWORK`, or `CHANGES_REQUESTED` when the source recommended next step + is not `HUMAN_DECISION`. +- `agent-self-approve` may hand off to `fix-pr` only for `REQUEST_CHANGES`. + `APPROVED` may hand off to `agent-self-merge` only when self-merge is + enabled; otherwise `APPROVED`, `BLOCKED`, and `FAILED` stop. +- `agent-self-merge` terminal conclusions stop. +- `fix-pr` may hand off to `review` only when fixes succeeded. When + `fix-pr` reports `no_changes`, `failed`, or `verify_failed`, choose a + visible stop/block path instead of asking for another automatic review. +- Issue-level `orchestrate` in agent mode may return `handoff` with + `next_action: "implement"` to implement the current issue directly when the + requested work is small and self-contained within that issue. +- Issue-level `orchestrate` in agent mode may return `delegate_issue` to + create, reuse, or adopt one child issue and start the child issue's normal + orchestrator flow. +- Pull-request-level `orchestrate` in agent mode may return `handoff` with + `next_action: "review"` or `next_action: "fix-pr"` for open PR targets. Use + `review` for analysis-only or review-first requests, and `fix-pr` only when + the user clearly wants branch changes or PR fixes. Use `answer`, `stop`, or + `blocked` when no follow-up workflow should run. +- Duplicate handoffs are skipped by the orchestrator marker dedupe logic. +- You may choose to stop when another automatic action is not useful, except + that enabled self-approval should receive `SHIP` and review `HUMAN_DECISION` + handoffs. + +## Instructions + +Read the target and relevant repository context as needed. Consider the latest +action result, the original task request, repository memory, and selected +rubrics. Then return exactly one JSON object and nothing else: + +```json +{ + "decision": "handoff | delegate_issue | answer | stop | blocked", + "next_action": "implement | review | fix-pr | agent-self-approve | agent-self-merge", + "reason": "Short explanation for logs and the handoff marker.", + "handoff_context": "Actionable instructions for the next action, especially fix-pr.", + "user_message": "Optional user-facing message to post when decision is answer or blocked.", + "clarification_request": "Optional focused question to post when decision is blocked.", + "child_stage": "Short child issue stage name when decision is delegate_issue.", + "child_instructions": "Concrete child issue task instructions when decision is delegate_issue.", + "child_issue_number": "Optional existing child issue number to reuse or adopt.", + "base_branch": "Optional branch to base implementation PRs on.", + "base_pr": "Optional PR number whose head branch implementation PRs should stack on." +} +``` + +Rules: +- If the latest review synthesis includes a `Recommended Next Step`, treat it + as the primary automation signal: hand off on `FIX_PR`, hand off to + `agent-self-approve` on `HUMAN_DECISION` when self-approval is enabled, and + stop on `HUMAN_DECISION` or `NO_AUTOMATED_ACTION` otherwise. +- Use `handoff` only when one more automatic action is clearly warranted. +- For issue-level `orchestrate`, prefer `handoff` with `next_action: + "implement"` when the requested work fits in the current issue. Use + `delegate_issue` when a separate child issue materially helps: high-level or + multi-stage management, explicit decomposition, adopting an existing child + issue, or isolating a distinct workstream. +- Use `delegate_issue` only for issue-level meta orchestration. Do not set + `next_action` with `delegate_issue`; it is an internal command, not a public + route. Provide either `child_instructions`, `handoff_context`, or + `child_issue_number`. +- For pull-request-level `orchestrate`, choose only `handoff` to `review`, + `handoff` to `fix-pr`, `answer`, `stop`, or `blocked`. Do not choose + `implement` or `delegate_issue` for PR targets. +- When `delegate_issue` continues sequential child implementation work after a + prior child finished with an open, unmerged PR, set `base_pr` to that prior + child PR so the next child stacks on it. Omit stack inputs only when the next + child is intentionally independent, and explain that independence in + `reason`. +- Be conservative for `MINOR_ISSUES`, especially in late rounds. Hand off to + `fix-pr` only for concrete unresolved findings that require a branch change + and are safe for an automated agent to apply. +- Use `stop` when the task appears complete, the result is unsupported, or the + next step should be left to a human. +- Stop instead of handing off when the remaining items are metadata-only + (for example PR title/body/labels/comments), optional suggestions, INFO-level + notes, style or naming preferences, already-fixed findings, or other + human-judgment nits. +- Use `blocked` when required context is missing or the chain cannot proceed + safely. Include `user_message` and/or `clarification_request` with text that + can be posted directly as the visible clarification comment. +- Use `answer` only as a top-level `decision` when the user asked a question or + needs guidance and no follow-up workflow should run. Put the visible response + in `user_message`. +- Do not use `answer` as `next_action`; if the automation needs to ask the user + a question before continuing, choose `blocked` with a clarification message. +- Omit `next_action` unless `decision` is `handoff`. +- Include `handoff_context` for `handoff` decisions when useful. For `fix-pr`, + it is required: preserve any non-empty source handoff context, or make the + task concrete by summarizing the exact review findings to address, + constraints to preserve, and unrelated work to avoid. +- When `agent-self-approve` returns `REQUEST_CHANGES`, hand off to `fix-pr` + and preserve the source handoff context as the fix-pr task. +- When `agent-self-approve` returns `APPROVED` and self-merge is enabled, hand + off to `agent-self-merge`. diff --git a/.github/prompts/agent-release.md b/.github/prompts/agent-release.md new file mode 100644 index 0000000..6ead155 --- /dev/null +++ b/.github/prompts/agent-release.md @@ -0,0 +1,35 @@ +## Task Description + +Prepare a Sepo release pull request for GitHub issue #${TARGET_NUMBER}. + +Instructions: +1. Read the current issue state with `gh issue view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,labels,state,url`. +2. Identify the release version from the issue title/body or latest human request. If no version was provided, determine the next version from `.agent/package.json`, recent repository changes, and `.agent/docs/technical-details/versioning.md`, then state the chosen version in the PR body. +3. Validate the version against `.agent/docs/technical-details/versioning.md`. +4. Update `.agent/package.json`; it is the canonical Sepo package/runtime version. +5. Update `.agent/package-lock.json` if package metadata changes require it. +6. Update `.agent/CHANGELOG.md` with release notes for this version. +7. Update docs or checklist entries that should change for this version. +8. Run lightweight, directly relevant checks when applicable. +9. Do not create git tags. Do not create or edit GitHub Releases. Do not publish packages. +10. Do not commit. Leave changes in the working tree. + +Return exactly one JSON object and nothing else: + +```json +{ + "summary": "One short paragraph for the workflow logs and issue comment.", + "commit_message": "Concise commit message under 72 characters.", + "pr_title": "Concise pull request title under 72 characters.", + "pr_body": "GitHub-flavored markdown pull request body." +} +``` + +Rules: +- `summary` should briefly describe the release preparation changes made and any verification run. +- `commit_message` should describe the actual release preparation change. +- `pr_title` should be specific to the selected release version. +- `pr_body` should be concise, clear, and ready to pass to `gh pr create --body-file`. +- Include issue-closing text for the target issue, for example `Closes #${TARGET_NUMBER}`. +- Keep the issue-closing line in the PR body itself. +- If you cannot safely prepare the release because the version is invalid, ambiguous, or violates policy, return empty strings for `commit_message`, `pr_title`, and `pr_body`, and explain the blocker in `summary`. diff --git a/.github/prompts/agent-self-approve.md b/.github/prompts/agent-self-approve.md new file mode 100644 index 0000000..49dbd48 --- /dev/null +++ b/.github/prompts/agent-self-approve.md @@ -0,0 +1,67 @@ +## Task Description + +Perform a high-level self-approval gate for pull request #${TARGET_NUMBER}. + +This is not a duplicate low-level code review. Decide whether the PR is aligned +with the repository's long-term goals, user/team rubrics, automation safety +expectations, and the right product direction for Sepo. Review the code again +carefully enough to avoid approving a change that is technically or strategically +unsafe. + +Gather current PR context before deciding: +- `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,files,labels,reviews,reviewDecision,state,url,headRefOid` +- `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` +- inspect the local repository patterns and relevant docs +- inspect selected rubrics and, when needed, browse `$RUBRICS_DIR` for active + rubrics that materially apply + +The workflow captured the PR head before this agent run: + +- Expected head SHA: `${SELF_APPROVE_EXPECTED_HEAD_SHA}` + +If this run came from review handoff, the orchestrator also passed: + +- Source review verdict: `${SELF_APPROVE_SOURCE_CONCLUSION}` +- Source recommended next step: `${SELF_APPROVE_SOURCE_RECOMMENDED_NEXT_STEP}` + +For `HUMAN_DECISION` review handoffs, make the decision here instead of +routing back to a human by default. Use `APPROVE` only when the trusted +current-head review verdict is `SHIP` and approval is safe. For non-`SHIP` +verdicts, return `REQUEST_CHANGES` when concrete follow-up is needed, or +`BLOCKED` only when safety checks, missing context, or automation limits prevent +a reliable decision. + +Rules: +- Do not mutate GitHub state. +- Do not submit a PR review yourself. +- Do not post comments directly with `gh`. +- Return exactly one JSON object and nothing else. +- Use `APPROVE` only when agent approval is genuinely appropriate. +- Use `REQUEST_CHANGES` when follow-up implementation work is appropriate. +- Use `BLOCKED` only when required context is missing, safety checks fail, or + automation cannot make a reliable decision. + +Ask and answer concrete questions about the implementation from these dimensions: + +Functionality: +- What behavior changed? Does the implementation match the issue/parent-plan scope? +- Is the change aligned with the repo's goal? Is the current implementation the right way to solve the problem? + +Code Quality: +- Does it contain "patched" code? Can you think of other cleaner or more idiomatic ways for implementing the function? +- Is any awkwardness acceptable for this slice, or should it become a required fix? + +Maintenance and Bug Handling: +- What happens in edge cases and reruns? +- Are the likely long-term maintenance and safety costs acceptable? + +Return: + +```json +{ + "verdict": "APPROVE | REQUEST_CHANGES | BLOCKED", + "reason": "Concise rationale for the self-approval decision.", + "handoff_context": "Concrete follow-up instructions when verdict is REQUEST_CHANGES; otherwise optional.", + "inspected_head_sha": "${SELF_APPROVE_EXPECTED_HEAD_SHA}" +} +``` diff --git a/.github/prompts/daily-summary.md b/.github/prompts/daily-summary.md new file mode 100644 index 0000000..ab17ffc --- /dev/null +++ b/.github/prompts/daily-summary.md @@ -0,0 +1,38 @@ +## Task Description + +Generate a concise daily report from recently synced GitHub activity. + +The request text includes the summary date, lookback window, and the absolute path to a signals directory produced earlier in this workflow. + +Read these signals first: +- `github-sync.json` — sync counts and cursor metadata +- `memory/github///*.json` — recently updated issues, pull requests, and discussions mirrored by the existing memory-sync code + +Instructions: +1. If a signal file is missing or empty, treat that signal as unavailable. +2. Report only what is visible in the synced GitHub activity window; do not imply a complete repository-wide status scan. +3. Do not mutate files and do not call GitHub write APIs. +4. Keep the report concise, factual, and actionable. +5. Use GitHub-flavored markdown. Do not include a preamble. + +Produce exactly these sections: + +## Recent Activity + +Summarize notable recently updated issues, pull requests, and discussions. If little changed, say so. + +## Recently Active PRs + +Mention only pull requests present in the synced signal files. + +## Recently Active Issues + +Mention only issues present in the synced signal files. + +## Recently Active Discussions + +Mention only discussions present in the synced signal files. + +## Follow-ups + +List 1-3 concrete next steps, or say there are no obvious follow-ups from the synced activity. diff --git a/.github/prompts/memory-pr-closed.md b/.github/prompts/memory-pr-closed.md new file mode 100644 index 0000000..abf0459 --- /dev/null +++ b/.github/prompts/memory-pr-closed.md @@ -0,0 +1,34 @@ +## Task Description + +A pull request in this repository was just closed. Update agent memory with any durable lessons worth carrying forward — no more, no less. + +Pull request: #${TARGET_NUMBER} at ${TARGET_URL} + +Instructions: +1. Read the PR history, not just the final state: + - `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,mergedAt,closedAt,state,files,labels,reviews,reviewDecision,baseRefName,headRefName,url` + - `gh api repos/${REPO_SLUG}/issues/${TARGET_NUMBER}/comments --paginate` for issue-comment history on the PR + - `gh api repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/comments --paginate` for inline review-comment history + - `gh api repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/reviews --paginate` for review history + - `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` if file-level changes matter for the lesson. +2. Follow linkage before composing updates. If the PR references parent issues, related PRs, or existing memory notes, read that linked context too. +3. Skim current memory before composing updates. At minimum read `${MEMORY_DIR}/PROJECT.md` and `${MEMORY_DIR}/MEMORY.md`. For broader lookups use the `memory/search.js` CLI. +4. Record a concise daily bullet for the PR closure, tracking the key task or outcome that landed: + - `node .agent/dist/cli/memory/update.js daily-append --dir "${MEMORY_DIR}" ""` + - Keep it factual, under ~140 characters, no PR number padding — the github/ mirror already links back. +5. Consider whether any **durable** memory update is warranted. A durable update is justified when the PR reveals: + - a stable convention or preference the team wants future runs to respect + - an architectural decision or constraint likely to outlast the next few weeks + - a recurring workflow rule (naming, review cadence, branch policy) that agents keep getting wrong + If no durable update is warranted, skip this step — most PRs produce zero `MEMORY.md` edits. +6. When a durable update is warranted, add it: + - `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file MEMORY.md --section Durable ""` + - Or surface a strategic question onto the project board: + - `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file PROJECT.md --section "Open Questions" ""` + - For simple bullet-shaped edits, prefer the CLI above. If a different note shape is warranted, you may edit repo-local memory files under `${MEMORY_DIR}` directly with normal tools while keeping the existing memory tree coherent. + +Guardrails: +- Prefer precise repo-specific statements over generic advice. +- Do not paste PR metadata (numbers, dates) into `MEMORY.md`. +- Do not `git commit` — the workflow does the commit and push. +- Return a short plain-text summary of what you recorded, or "no memory changes" if you chose not to touch memory. diff --git a/.github/prompts/memory-scan.md b/.github/prompts/memory-scan.md new file mode 100644 index 0000000..49ab46a --- /dev/null +++ b/.github/prompts/memory-scan.md @@ -0,0 +1,31 @@ +## Task Description + +This is a scheduled maintenance run of repository memory. No specific user request — you are deciding what (if anything) to memorize from recent repository activity. + +Instructions: +1. Read recent activity. The sync workflow mirrors history under `${MEMORY_DIR}/github/`: + - `${MEMORY_DIR}/github///issue-*.json` + - `${MEMORY_DIR}/github///pull-*.json` + - `${MEMORY_DIR}/github///discussion-*.json` + For broader queries, use `node .agent/dist/cli/memory/search.js --dir "${MEMORY_DIR}" ""`. + If a mirrored issue/PR/discussion references parent issues, related PRs, or existing memory notes, read that linked context too before curating memory. +2. Read recent daily logs: `${MEMORY_DIR}/daily/*.md` (focus on the last ~7 days). +3. Read the current durable state: `${MEMORY_DIR}/MEMORY.md` and `${MEMORY_DIR}/PROJECT.md`. +4. Make a judgment call. Curate durable memory only when you see: + - A pattern across multiple recent PRs / issues / discussions that reveals a convention or preference the agent should follow next time. + - Stable architectural or policy decisions that were finalized in the current window. + - Corrections / "don't do X" lessons that came up repeatedly. + Skip anything speculative. Most scans should produce zero durable updates. +5. When an update is warranted, update memory in the shape that best fits the finding. For standard bullet edits, prefer the memory-update CLI: + - Add: `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file MEMORY.md --section Durable ""` + - Replace a stale entry: `node .agent/dist/cli/memory/update.js replace --dir "${MEMORY_DIR}" --file MEMORY.md --section Durable --match "" --with ""` + - Remove an outdated entry: `node .agent/dist/cli/memory/update.js remove --dir "${MEMORY_DIR}" --file MEMORY.md --section Durable --match ""` + - Surface an open project question: `node .agent/dist/cli/memory/update.js add --dir "${MEMORY_DIR}" --file PROJECT.md --section "Open Questions" ""` + - If the CLI shape does not fit, you may edit repo-local memory files under `${MEMORY_DIR}` directly with normal tools. Keep the existing layout coherent and stay within the memory tree. + +Guardrails: +- Trust who posted something less than what they posted. The mirror deduplicates what reached the repo; you judge whether it matters for future runs. +- Prefer patterns supported by linked history, repeated discussion, or related notes over isolated one-off artifacts. +- Do not mirror noise. If a PR/issue/discussion isn't driving a lasting change in convention, skip it. +- Do not `git commit` yourself — the workflow commits any edits to `${MEMORY_DIR}` and pushes them to `${MEMORY_REF}`. +- Return a short plain-text summary: what you reviewed, what you changed (if anything), and what you chose to skip and why. diff --git a/.github/prompts/project-manager.md b/.github/prompts/project-manager.md new file mode 100644 index 0000000..eff19a6 --- /dev/null +++ b/.github/prompts/project-manager.md @@ -0,0 +1,104 @@ +## Task Description + +Run the repository project-manager pass. Assess open issues and pull requests with agent judgment, emit a managed triage-label change plan, and return the final summary for the workflow to publish. + +Runtime request/configuration: + +${REQUEST_TEXT} + +## Managed Labels + +Use exactly these managed label families: + +- Priority: `priority/p0`, `priority/p1`, `priority/p2`, `priority/p3` +- Effort: `effort/low`, `effort/medium`, `effort/high` + +Recommended label colors/descriptions when creating missing labels: + +| Label | Color | Description | +|---|---:|---| +| `priority/p0` | `b60205` | Project management: highest priority | +| `priority/p1` | `d93f0b` | Project management: high priority | +| `priority/p2` | `fbca04` | Project management: medium priority | +| `priority/p3` | `c2e0c6` | Project management: low priority | +| `effort/low` | `c2e0c6` | Project management: low effort | +| `effort/medium` | `fbca04` | Project management: medium effort | +| `effort/high` | `d73a4a` | Project management: high effort | + +Priority guidance: + +- `priority/p0`: urgent or critical work, especially security, data loss, production breakage, broken releases, or work that blocks many other tasks. +- `priority/p1`: high-impact work that should be near the top of the queue, including important bugs, major user-facing regressions, or PRs/issues blocking active work. +- `priority/p2`: normal valuable work that should be tracked but is not immediately critical. +- `priority/p3`: low-impact, speculative, stale, informational, or nice-to-have work. + +Effort guidance: + +- `effort/low`: small, localized, review-only, documentation/copy, typo, or straightforward follow-up. +- `effort/medium`: normal implementation/review work with moderate scope or uncertainty. +- `effort/high`: broad, risky, cross-cutting, architectural, migration, security-sensitive, or multi-step work. + +## Process + +1. Determine the effective repository and limit from the runtime request. Default to `${REPO_SLUG}` and limit `100` per kind if unspecified. +2. List open issues and pull requests with `gh`: + - `gh issue list --repo ${REPO_SLUG} --state open --limit --json number,title,body,labels,createdAt,updatedAt,comments,assignees` + - `gh pr list --repo ${REPO_SLUG} --state open --limit --json number,title,body,labels,createdAt,updatedAt,comments,assignees,isDraft,reviewDecision` +3. Use judgment from titles, bodies, labels, recency, discussion volume, assignment, draft/review status, and repository context. Do not reduce the decision to keyword heuristics. +4. Assign each considered item exactly one managed priority label and exactly one managed effort label. +5. Compute planned label changes by removing stale managed priority/effort labels that do not match the chosen labels and adding missing chosen labels. Do not remove unrelated labels. +6. Do not mutate labels, even when label application is enabled. The workflow has a deterministic post-agent step that validates and applies only allowed managed-label operations. +7. Do not create labels, issues, pull requests, commits, branches, reviews, or discussion comments. The workflow has separate deterministic final steps for managed labels and summary publication. + +## Final Output + +Return only GitHub-flavored markdown. This response is the project-management summary that the workflow will pass to deterministic label application, write to the Actions step summary, and may post to the Daily Summary discussion. + +Use this structure: + +## Project Management Summary + +- Mode: `dry run`, `labels applied`, or `labels not applied` +- Open items assessed: ` issues, pull requests` +- Managed labels: `priority/*`, `effort/*` + +### Top Triage Queue + +List the top 5-10 items sorted by your assessed priority and actionability. For each item include: + +- `issue#N` or `pull_request#N` +- title +- selected priority and effort labels +- concise rationale +- applied or planned label changes + +### Label Changes + +Summarize applied changes, planned dry-run changes, or say no changes were needed. + +Include the structured change plan in one fenced `json` block using exactly this shape: + +```json +{ + "label_changes": [ + { + "kind": "issue", + "number": 123, + "add": ["priority/p1", "effort/medium"], + "remove": ["priority/p3"] + }, + { + "kind": "pull_request", + "number": 456, + "add": ["priority/p2"], + "remove": [] + } + ] +} +``` + +Use only `kind` values `issue` or `pull_request`. Use only managed labels in `add` and `remove`: `priority/p0`, `priority/p1`, `priority/p2`, `priority/p3`, `effort/low`, `effort/medium`, `effort/high`. + +### Notes + +Include any assumptions, skipped items, failures, or follow-ups. Keep this concise. diff --git a/.github/prompts/review-synthesize-finalize.md b/.github/prompts/review-synthesize-finalize.md new file mode 100644 index 0000000..633a97a --- /dev/null +++ b/.github/prompts/review-synthesize-finalize.md @@ -0,0 +1,33 @@ +## Task Description + +You are resuming a PR review synthesis session that hit the turn limit before +producing the final markdown. + +Do not repeat the exploration work unless it is strictly necessary. +Use the existing session context and produce the final unified review synthesis +now. + +Requirements: +- Output clean GitHub-flavored markdown only +- Do not output JSON +- Do not include a preamble +- Keep the same synthesis structure and verdict style as the original task, + including: + - `## Summary of PR/Issue` + - `## Review` with the findings table + - `## Progress` + - `## Issue Details` with `
` blocks when applicable + - `## Recommended Next Step` + - `## Final Verdict` + - `## Action Items` +- Check reviews and comments already posted by other agents before finalizing, + and incorporate them into the synthesis. +- If the session already identified line-specific issues that still need inline + PR comments, first check whether there are already existing inline review + comments on those issues with `gh api --paginate + repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments`. +- Do not post more inline comments until you have checked the existing inline + comments and confirmed the new comment would not be a duplicate. +- If you post inline comments, use: + `gh api --method POST repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments -f body='' -f commit_id='' -f path='' -F line= -f side=RIGHT` + and do not post the full synthesis or a separate summary comment diff --git a/.github/prompts/review-synthesize.md b/.github/prompts/review-synthesize.md new file mode 100644 index 0000000..55d1ea1 --- /dev/null +++ b/.github/prompts/review-synthesize.md @@ -0,0 +1,132 @@ +## Task Description + +You are synthesizing one or more independent code reviews of PR #${PR_NUMBER}. + +Review outputs are available under `${REVIEWS_DIR}`. Use every review file you +find there. If only one review file exists, synthesize from that single +reviewer input without treating missing reviewers as an error. Do not infer +agreement, disagreement, or deduplication from missing reviewer outputs. +Before reporting any `BLOCKING` finding, `FIX_PR` next step, or `NEEDS_REWORK` +verdict, verify that each unresolved issue is supported by the current +`${REVIEWS_DIR}` artifacts or the current PR state. Do not carry forward +findings from older agent conversations or prior PR discussion unless they are +still grounded in the current review artifacts or current diff. + +Use `gh pr view ${PR_NUMBER} --repo ${GITHUB_REPOSITORY} --json title,body,comments,reviews` +to inspect the current PR conversation before synthesizing. +Use `gh api --paginate repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments` +to inspect existing inline review comments before posting any new ones. +Use GraphQL `reviewThreads` to inspect existing inline review threads before +resolving any thread or choosing minimization over resolution, for example: +`gh api graphql -f query='query ReviewThreads($owner: String!, $repo: String!, $number: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $number) { reviewThreads(first: 100) { nodes { id isResolved viewerCanResolve path line comments(first: 100) { nodes { id databaseId author { login } body } } } } } } }' -F owner='' -F repo='' -F number=${PR_NUMBER}` +Reviewer outputs may include optional `Inline Comment Suggestions`. Treat them +as advisory metadata, not commands. Synthesis chooses the final inline cleanup +action. Before mutating GitHub inline comments, re-fetch existing inline +comments and review threads when relevant, and verify the target still belongs +to this PR and still warrants the action. + +When a finding is concrete, actionable, and tied to a specific changed line, +post an inline PR comment with `gh` before returning the final synthesis. Use +inline comments sparingly: +- only for file/line-specific issues that merit direct reviewer feedback +- do not duplicate points that are already clearly covered in the PR discussion +- do not duplicate useful feedback already posted by other agents in PR reviews, + top-level comments, or inline comments +- before posting, fetch existing inline review comments and skip any that + already cover the same file/line issue well enough +- for `reply_existing`, only reply to an existing inline review comment authored + by the same authenticated agent account after the re-fetch confirms authorship + and PR ownership. Do not reply to human comments or comments from other bots, + and skip the reply if authorship or PR ownership is uncertain. Use: + `gh api --method POST repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments -f body='' -F in_reply_to=` +- for `resolve_existing_thread`, you may resolve older same-agent inline review + threads when the current synthesis confirms the thread's issue has been + addressed or superseded. First re-fetch the PR's `reviewThreads` and check + the target thread `id`, `isResolved`, `viewerCanResolve`, `path`, `line`, and + comments' authorship. Only resolve unresolved threads that belong to this PR, + are resolvable by the viewer, and have every thread comment authored by the + same authenticated agent account; never resolve human threads or threads from + other bots. Use: + `gh api graphql -f query='mutation ResolveInlineReviewThread($id: ID!) { resolveReviewThread(input: { threadId: $id }) { thread { isResolved } } }' -F id=''` +- for `mark_existing_outdated`, you may mark older same-agent inline comments as + outdated when the current synthesis supersedes them and there is no + appropriate resolvable same-agent review-thread path. Prefer thread + resolution over minimization when the same issue maps to an unresolved, + viewer-resolvable, same-agent thread on this PR. Only minimize comments + authored by the same authenticated agent account, only use the existing + comment's `node_id`, and never minimize human comments or comments from other + bots. Use: + `gh api graphql -f query='mutation MinimizeInlineReviewComment($id: ID!) { minimizeComment(input: { subjectId: $id, classifier: OUTDATED }) { minimizedComment { isMinimized } } }' -F id=''` +- do not delete inline comments +- do not reply to, resolve, or minimize anything when authorship, PR ownership, + supersession, or resolution confidence is uncertain +- summarize any inline comments posted, replies added, comments minimized, or + threads resolved in the final synthesis `Progress` section +- do not post the full synthesis, a top-level summary, or a separate overall PR + comment with `gh`; the workflow posts the final synthesis itself +- if needed, use `gh pr view ${PR_NUMBER} --repo ${GITHUB_REPOSITORY} --json files,headRefOid` and + `gh api --paginate repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments` + to compare against existing feedback before posting +- post new inline comments with this command shape: + `gh api --method POST repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments -f body='' -f commit_id='' -f path='' -F line= -f side=RIGHT` + +Produce a unified review synthesis: +1. Deduplicate overlapping findings and note meaningful reviewer disagreements +2. Prioritize BLOCKING > WARNING > INFO and use those exact severity labels +3. Make the top of the synthesis easy to scan before readers open details +4. Add a "Progress" section describing what is already acknowledged or fixed +5. Add a "Recommended Next Step" section that labels the ideal next step for + automation and humans +6. End with a final verdict: SHIP / MINOR_ISSUES / NEEDS_REWORK +7. End with an "Action items" section as a GitHub checkbox list (`- [ ]`) + +Format as clean GitHub-flavored markdown with this structure: + +## Summary of PR/Issue +- 3-5 sentences summarizing what the PR is trying to do and why + +## Review +- 1-3 sentences with the overall judgment +- Then a findings table with exactly these columns: + +| Issue | Severity | Description | +| -- | -- | -- | +| ... | BLOCKING/WARNING/INFO | 1-2 sentences max | + +## Progress +- Brief bullets for anything already acknowledged, fixed, or intentionally left + out of scope + +## Issue Details +- For each actionable issue in the table, add one `
` block whose + summary starts with the same issue title used in the table +- Keep each block concise and focused +- Within each block, use: + - `**Cause:**` + - `**Candidate solutions:**` + - `**Comments:**` only when it adds real value, such as reviewer + disagreement, rollout risk, or fix status + +## Recommended Next Step +- Exactly one of: + - `FIX_PR`: unresolved findings require a concrete branch change and are safe + for an automated fix-pr pass. + - `HUMAN_DECISION`: remaining concerns are metadata-only, optional, product or + style judgment, ambiguous, or need maintainer choice before more automation. + - `NO_AUTOMATED_ACTION`: no unresolved actionable work remains. +- Include one sentence explaining why. + +## Final Verdict +- `SHIP`, `MINOR_ISSUES`, or `NEEDS_REWORK` + +## Action Items +- GitHub checkbox list using `- [ ]` +- Include only required, concrete branch-change work in checkboxes. Keep optional + INFO notes, metadata-only cleanup, and human-judgment nits out of automation + action items unless the PR request explicitly makes them required. + +If there are no actionable issues, include a single findings-table row that says +so, omit "Issue Details", set Recommended Next Step to `NO_AUTOMATED_ACTION`, +and keep the verdict consistent with that outcome. + +Do not include a preamble. diff --git a/.github/prompts/review.md b/.github/prompts/review.md new file mode 100644 index 0000000..b58ebe7 --- /dev/null +++ b/.github/prompts/review.md @@ -0,0 +1,69 @@ +## Task Description + +Perform a thorough code review of this pull request. + +Gather current PR context before judging the change: +- `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,files,labels,reviews,reviewDecision,state,url` +- `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json files,headRefOid` +- `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` +- use `git` and local file reads to inspect repository patterns and base-branch code + +The checked-out repository reflects the PR base branch for workflow safety, so +treat the live PR diff as the source of truth for proposed changes. + +This review phase must not mutate GitHub state: +- do not submit a PR review with `gh` +- do not post inline review comments +- do not post top-level PR comments +- return your review only as markdown in the final response +- inspect existing inline review comments with + `gh api --paginate repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/comments` + before recommending line-specific feedback +- inspect existing review threads with GraphQL `reviewThreads` before + recommending a thread-resolution suggestion, for example: + `gh api graphql -f query='query ReviewThreads($owner: String!, $repo: String!, $number: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $number) { reviewThreads(first: 100) { nodes { id isResolved viewerCanResolve path line comments(first: 100) { nodes { id databaseId author { login } body } } } } } } }' -F owner='' -F repo='' -F number=${TARGET_NUMBER}` + Use the thread node `id` as `existing_thread_id` when suggesting + `resolve_existing_thread`. +- if a finding deserves line-specific feedback, include the exact `path`, `line`, + and suggested comment body so the review synthesis agent can post it later + with: + `gh api --method POST repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/comments -f body='' -f commit_id='' -f path='' -F line= -f side=RIGHT` +- You may include an optional `Inline Comment Suggestions` section using this + shape when existing inline comments affect what synthesis should do: + - `action`: `open_new`, `reply_existing`, `resolve_existing_thread`, + `mark_existing_outdated`, or `no_action` + - `path`, `line` + - `finding`: concise issue context used for dedupe and rationale + - `suggested_body`: exact postable comment text for synthesis to use if it + acts on the suggestion + - `existing_comment_id` for replies, GraphQL `existing_thread_id` for + resolution when known, and `existing_comment_node_id` for minimization when + known + - `rationale` + Cleanup suggestions are advisory. Suggest `resolve_existing_thread` only when + the fetched thread appears same-agent, unresolved, viewer-resolvable, on this + PR, and the issue appears addressed or superseded. Suggest + `mark_existing_outdated` only for older same-agent inline comments that appear + superseded when no appropriate resolvable review-thread path is known. Use + `no_action` when authorship, PR ownership, supersession, or resolution + confidence is uncertain. + These are suggestions only; do not mutate GitHub from the reviewer lane. + +Review in this order: + +0. Understand the goal first. Identify the underlying problem, the ideal target state, and the most principled path to that target before drilling into details. Decide whether the PR is solving the right problem in the right way. Consider existing repository patterns first. If the prior review context has not already done it and the choice materially affects the judgment, search for relevant libraries, framework features, or platform guidance and note whether they offer a better-supported implementation. +1. Design critique: is the design easy to extend, and does it avoid rebuilding wheels badly when an existing repository pattern, library, or platform capability would be clearer? +2. Implementation quality: bugs, regressions, security or trust-boundary issues, performance problems, and hacky, brittle, or unnecessarily complex code or solutions. +3. Tests: are the risky parts covered by real, meaningful tests that exercise behavior rather than only shallow happy paths? +4. Documentation and workflow fit: are the docs, prompts, and workflow notes the most efficient way to communicate the change, and do workflow or automation changes make operational sense? + +Categorize each finding as: +- **BLOCKING** +- **WARNING** +- **INFO** + +End with: +1. An overall verdict: SHIP / MINOR_ISSUES / NEEDS_REWORK +2. A "Files to Review" section listing the most important changed files and why + +Format as clean GitHub-flavored markdown. diff --git a/.github/prompts/rubrics-initialization.md b/.github/prompts/rubrics-initialization.md new file mode 100644 index 0000000..245590a --- /dev/null +++ b/.github/prompts/rubrics-initialization.md @@ -0,0 +1,78 @@ +## Task Description + +Initialize the dedicated user/team rubrics branch for this repository. + +Rubrics are not memory. Memory records agent/project continuity; rubrics encode what users want future agent work to optimize for and be evaluated against. + +The branch skeleton has already been created under `${RUBRICS_DIR}`. Your job is to populate initial rubric YAML files when there is enough trusted evidence. + +Initialization context: + +${REQUEST_TEXT} + +Instructions: +1. Read existing rubrics under `${RUBRICS_DIR}/rubrics/` before making changes. +2. Use the initialization context above as the highest-priority direction. It may include links to PRs, issues, comments, design notes, or plain-language preferences. +3. If initialization context is empty or too sparse, inspect repository history for durable preferences: + - `gh pr list --repo ${REPO_SLUG} --state merged --limit 20 --json number,title,body,author,mergedAt,labels,url` + - for promising PRs, use `gh pr view`, issue comments, review comments, reviews, and diffs as needed + - inspect recent issues only when they contain explicit agent-workflow or implementation-quality preferences +4. Determine trusted contributors before learning from conversation: + - Identify the repository owner and primary maintainers on a best-effort + basis: + - `gh repo view ${REPO_SLUG} --json owner,nameWithOwner` + - `gh api repos/${REPO_SLUG}/collaborators --paginate --jq '.[] | select(.permissions.admin or .permissions.maintain) | {login: .login, type: .type, permissions: .permissions}'` + when the token has permission. If this is unavailable, rely on each + comment/review's author metadata instead. + - For every candidate source, inspect the comment/review author's login, + user type, and GitHub `author_association` / `authorAssociation` value. + - Treat repository-owner comments and direct admin/maintain collaborator + comments as the primary source of user/team preference. + - Treat GitHub `author_association` / `authorAssociation` values `OWNER`, + `MEMBER`, and `COLLABORATOR` as trusted contributor signals, but use + non-primary maintainer comments as corroborating evidence rather than the + sole basis for a new rubric. + - Treat `CONTRIBUTOR`, `FIRST_TIMER`, `FIRST_TIME_CONTRIBUTOR`, `NONE`, + and missing associations as untrusted for rubric learning unless a trusted + contributor explicitly endorses the same preference. + - Treat bot and agent-authored comments/reviews as advisory evidence only; + do not convert them into user/team preference unless a trusted contributor + explicitly agrees with the point. +5. Add initial rubrics only when trusted evidence reveals a stable user/team preference, such as: + - repeated reviewer feedback about implementation quality + - explicit user preference about coding style, workflow, review quality, or communication + - durable expectations future agents should follow +6. Skip one-off comments, speculative preferences, repository facts, and preferences already covered by existing active rubrics. +7. Store one rubric per YAML file under `${RUBRICS_DIR}/rubrics//`, + such as `coding/`, `communication/`, or `workflow/`. Directory names are + organizational; the schema `domain` field is the source of truth. + Use the most specific source URL available in `examples[].source`, such as a + PR review comment or issue comment URL, rather than only the PR URL. +8. Use `status: draft` when the preference seems useful but is not yet strongly established. +9. Do not `git commit`; the workflow validates and commits rubrics after the run. +10. If there is not enough trusted evidence, leave only the initialized skeleton and return `no initial rubric changes`. + +Rubric schema: + +```yaml +schema_version: 1 +id: kebab-case-stable-id +title: Short human-readable title +description: >- + The user/team preference future agents should follow or be evaluated against. +type: generic # generic | specific +domain: coding_workflow # coding_style | coding_workflow | communication | review_quality +applies_to: + - implement # implement | fix-pr | review | agent-self-approve | agent-self-merge | answer | skill | rubrics-review | rubrics-initialization | rubrics-update +severity: should # must | should | consider +weight: 3 # 1-10 +status: active # active | draft | retired +examples: + - source: https://github.com/self-evolving/repo/pull/123#discussion_r123456789 + note: Specific trusted reviewer/user comment that demonstrates why this rubric exists. +``` + +Return a short markdown summary of what you changed, including: +- created rubric IDs and file paths +- sources used +- any notable skipped or ambiguous evidence diff --git a/.github/prompts/rubrics-review.md b/.github/prompts/rubrics-review.md new file mode 100644 index 0000000..40af948 --- /dev/null +++ b/.github/prompts/rubrics-review.md @@ -0,0 +1,48 @@ +## Task Description + +Review pull request #${TARGET_NUMBER} specifically against the selected user/team rubrics. + +Rubrics represent what users want the agent to optimize for. Your job is not to do a general code review; focus on whether this implementation satisfies the applicable rubrics. + +Gather current PR context before scoring: +- `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,comments,files,labels,reviews,reviewDecision,state,url,headRefOid` +- `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` +- use the local checkout for repository patterns, but treat the live PR diff as the source of truth + +Rules: +- Do not mutate GitHub state. +- Do not post comments directly with `gh`. +- Return only markdown; the caller will upload or synthesize it. +- If no rubrics were selected, say so and give `N/A` as the score. +- The rubrics context may contain the full active rubric set. Decide which rubrics genuinely apply to this PR, and do not score unrelated route/process rubrics. +- Score only against rubrics that genuinely apply to the PR. +- Cite concrete evidence from the PR diff, tests, docs, or discussion. +- Begin with the score table. Put explanatory prose after the score table as bullets. +- Use `
` / `` only for evidence that would make the main comment too long. + +Format: + +```md +## Rubrics Review + +| Total Score | Verdict | Rubrics Scored | +| -- | -- | -- | +| <0-100 or N/A> | PASS / PARTIAL / FAIL / N/A | | + +| Dimension | Rubric | Result | Score | Evidence | +| -- | -- | -- | -- | -- | +| | | pass/partial/fail/not applicable | <points/max or N/A> | <brief evidence> | + +## Notes + +- <brief explanation of the most important score drivers> +- <smallest useful follow-up, or "No rubric-specific follow-up needed."> + +## Findings + +- **BLOCKING/WARNING/INFO:** <finding tied to a rubric, if any> + +## Final Rubric Verdict + +PASS / PARTIAL / FAIL / N/A +``` diff --git a/.github/prompts/rubrics-update.md b/.github/prompts/rubrics-update.md new file mode 100644 index 0000000..d33d886 --- /dev/null +++ b/.github/prompts/rubrics-update.md @@ -0,0 +1,84 @@ +## Task Description + +A pull request in this repository was just merged, or was selected manually for rubric learning. Update the dedicated user/team rubrics branch with durable preferences learned from the PR conversation — no more, no less. + +Pull request: #${TARGET_NUMBER} at ${TARGET_URL} + +Rubrics are not memory. Memory records agent/project continuity; rubrics encode what users want future agent work to optimize for and be evaluated against. + +Instructions: +1. Read the PR history, not just the final state: + - `gh pr view ${TARGET_NUMBER} --repo ${REPO_SLUG} --json title,body,author,mergedAt,closedAt,state,files,labels,reviews,reviewDecision,baseRefName,headRefName,url` + - `gh api repos/${REPO_SLUG}/issues/${TARGET_NUMBER}/comments --paginate` + - `gh api repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/comments --paginate` + - `gh api repos/${REPO_SLUG}/pulls/${TARGET_NUMBER}/reviews --paginate` + - `gh pr diff ${TARGET_NUMBER} --repo ${REPO_SLUG}` if file-level changes matter. +2. Read existing rubrics under `${RUBRICS_DIR}/rubrics/` before proposing changes. +3. Determine which commenters are trusted project contributors before learning: + - Identify the repository owner and primary maintainers on a best-effort + basis: + - `gh repo view ${REPO_SLUG} --json owner,nameWithOwner` + - `gh api repos/${REPO_SLUG}/collaborators --paginate --jq '.[] | select(.permissions.admin or .permissions.maintain) | {login: .login, type: .type, permissions: .permissions}'` + when the token has permission. If this is unavailable, rely on each + comment/review's author metadata instead. + - For every candidate source, inspect the comment/review author's login, + user type, and GitHub `author_association` / `authorAssociation` value. + The `Requested by` runtime field identifies who started this run. On + automatic merged-PR rubrics-update runs, it is the actor that closed/merged + the PR; if that same actor authored an explicit request to add or update a + rubric, treat that source as trusted even when best-effort collaborator or + association lookup is incomplete. This exception applies only to content + authored by `REQUESTED_BY`; it does not make other PR conversation + participants trusted. + - Treat repository-owner comments and direct admin/maintain collaborator + comments as the primary source of user/team preference. + - Treat GitHub `author_association` / `authorAssociation` values `OWNER`, + `MEMBER`, and `COLLABORATOR` as trusted contributor signals. A clear + instruction from one of these actors to add/update rubrics, or a durable + "future agents should..." preference, is sufficient basis for a rubric; + use vague non-primary maintainer comments as corroborating evidence rather + than the sole basis for a new rubric. + - Treat `CONTRIBUTOR`, `FIRST_TIMER`, `FIRST_TIME_CONTRIBUTOR`, `NONE`, + and missing associations as untrusted for rubric learning unless a trusted + contributor explicitly endorses the same preference. + - Treat bot and agent-authored comments/reviews as advisory evidence only; + do not convert them into user/team preference unless a trusted contributor + explicitly agrees with the point. + - When in doubt, prefer `no rubric changes` over learning from ambiguous or + untrusted feedback. +4. Add or update a rubric only when trusted contributor interaction reveals a stable user/team preference, such as: + - repeated reviewer feedback about implementation quality + - explicit user preference about coding style, workflow, review quality, or communication + - a durable expectation future agents should follow +5. Skip one-off comments, speculative preferences, and facts already covered by existing active rubrics. +6. Store one rubric per YAML file under `${RUBRICS_DIR}/rubrics/<domain>/`. + Use the most specific source URL available in `examples[].source`, such as a + PR review comment or issue comment URL, rather than only the PR URL. +7. Do not `git commit`; the workflow validates and commits rubrics after the run. + +Rubric schema: + +```yaml +schema_version: 1 +id: kebab-case-stable-id +title: Short human-readable title +description: >- + The user/team preference future agents should follow or be evaluated against. +type: generic # generic | specific +domain: coding_workflow # coding_style | coding_workflow | communication | review_quality +applies_to: + - implement # implement | fix-pr | review | agent-self-approve | agent-self-merge | answer | skill | rubrics-review | rubrics-initialization | rubrics-update +severity: should # must | should | consider +weight: 3 # 1-10 +status: active # active | draft | retired +examples: + - source: https://github.com/self-evolving/repo/pull/${TARGET_NUMBER}#discussion_r123456789 + note: Specific reviewer/user comment that demonstrates why this rubric exists. +``` + +Guardrails: +- Prefer updating an existing rubric over creating a near-duplicate. +- Keep titles concise and descriptions actionable. +- Use `status: draft` when the preference seems useful but not yet strongly established. +- Use `severity: must` sparingly for clear, repeated, high-confidence requirements. +- Return a short summary of what you changed, or `no rubric changes` if nothing warranted an update. diff --git a/.github/workflows/agent-approve.yml b/.github/workflows/agent-approve.yml new file mode 100644 index 0000000..a7b9c26 --- /dev/null +++ b/.github/workflows/agent-approve.yml @@ -0,0 +1,119 @@ +name: Agent / Approve + +on: + issue_comment: + types: [created] + discussion_comment: + types: [created] + +concurrency: + group: >- + agent-approve-${{ github.repository }}-${{ github.event.issue.number || github.event.discussion.number }} + cancel-in-progress: false + +permissions: + actions: write + contents: read + discussions: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +jobs: + approve: + if: >- + contains( + github.event.comment.body, + format('{0} /approve', vars.AGENT_HANDLE || '@sepo-agent') + ) + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Resolve approval target + id: approval + env: + ACCESS_POLICY: ${{ vars.AGENT_ACCESS_POLICY || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REPOSITORY_PRIVATE: ${{ github.event.repository.private && 'true' || 'false' }} + INPUT_MENTION: ${{ vars.AGENT_HANDLE || '@sepo-agent' }} + run: node .agent/dist/cli/resolve-approval.js + + - name: Create implementation issue + if: >- + steps.approval.outputs.should_dispatch == 'true' && + steps.approval.outputs.should_create_issue == 'true' + id: create_issue + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + ISSUE_BODY: ${{ steps.approval.outputs.issue_body }} + ISSUE_TITLE: ${{ steps.approval.outputs.issue_title }} + SOURCE_KIND: ${{ steps.approval.outputs.target_kind }} + TARGET_URL: ${{ steps.approval.outputs.target_url }} + run: node .agent/dist/cli/create-issue.js + + - name: Dispatch follow-up workflow + if: >- + steps.approval.outputs.should_dispatch == 'true' && + steps.approval.outputs.workflow == 'agent-implement.yml' + env: + APPROVAL_COMMENT_URL: ${{ github.event.comment.html_url }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ISSUE_NUMBER: ${{ steps.create_issue.outputs.issue_number || steps.approval.outputs.target_number }} + IMPLEMENTATION_ROUTE: ${{ steps.approval.outputs.route }} + REQUESTED_BY: ${{ github.actor }} + REQUEST_TEXT: ${{ steps.approval.outputs.request_text }} + AUTOMATION_MODE: ${{ vars.AGENT_AUTOMATION_MODE || 'agent' }} + AUTOMATION_MAX_ROUNDS: ${{ vars.AGENT_AUTOMATION_MAX_ROUNDS || '12' }} + run: node .agent/dist/cli/dispatch-agent-implement.js + + - name: Reject unsupported follow-up workflow + if: >- + steps.approval.outputs.should_dispatch == 'true' && + steps.approval.outputs.workflow != 'agent-implement.yml' + env: + WORKFLOW: ${{ steps.approval.outputs.workflow }} + run: | + echo "Unsupported workflow ${WORKFLOW}" >&2 + exit 1 + + - name: React with thumbs up + if: steps.approval.outputs.should_dispatch == 'true' + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + REACTION_SUBJECT_ID: ${{ github.event.comment.node_id }} + REACTION_CONTENT: THUMBS_UP + run: node .agent/dist/cli/add-reaction.js + + - name: Update approval request comment + if: steps.approval.outputs.should_dispatch == 'true' + env: + APPROVER: ${{ github.actor }} + CREATED_ISSUE_URL: ${{ steps.create_issue.outputs.issue_url }} + IS_DISCUSSION: ${{ steps.approval.outputs.is_discussion }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REQUEST_COMMENT_BODY: ${{ steps.approval.outputs.request_comment_body }} + REQUEST_COMMENT_ID: ${{ steps.approval.outputs.request_comment_id }} + ROUTE: ${{ steps.approval.outputs.route }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + WORKFLOW: ${{ steps.approval.outputs.workflow }} + run: node .agent/dist/cli/update-approval-comment.js diff --git a/.github/workflows/agent-branch-cleanup.yml b/.github/workflows/agent-branch-cleanup.yml new file mode 100644 index 0000000..59de2a9 --- /dev/null +++ b/.github/workflows/agent-branch-cleanup.yml @@ -0,0 +1,85 @@ +name: Agent Branch Cleanup + +on: + pull_request_target: + types: [closed] + +permissions: + contents: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +jobs: + cleanup: + if: >- + github.event.pull_request.merged == true && + github.event.pull_request.head.repo.full_name == github.repository && + startsWith(github.event.pull_request.head.ref, 'agent/') && + github.event.pull_request.head.ref != (vars.AGENT_MEMORY_REF || 'agent/memory') && + github.event.pull_request.head.ref != (vars.AGENT_RUBRICS_REF || 'agent/rubrics') + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - uses: actions/github-script@v7 + with: + github-token: ${{ steps.auth.outputs.token }} + script: | + const branch = context.payload.pull_request?.head?.ref; + const retargetBase = context.payload.pull_request?.base?.ref; + + if (!branch) { + core.setFailed("Missing pull request head ref."); + return; + } + + if (!retargetBase) { + core.setFailed("Missing pull request base ref."); + return; + } + + const dependentPulls = await github.paginate(github.rest.pulls.list, { + owner: context.repo.owner, + repo: context.repo.repo, + state: "open", + base: branch, + per_page: 100, + }); + + for (const pull of dependentPulls) { + core.info(`Retargeting dependent PR #${pull.number} from ${branch} to ${retargetBase}.`); + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: pull.number, + base: retargetBase, + }); + } + + try { + await github.rest.git.deleteRef({ + owner: context.repo.owner, + repo: context.repo.repo, + ref: `heads/${branch}`, + }); + core.info(`Deleted merged agent branch ${branch}.`); + } catch (error) { + if (error && typeof error === "object" && "status" in error && error.status === 404) { + core.info(`Branch ${branch} was already deleted.`); + return; + } + + throw error; + } diff --git a/.github/workflows/agent-close-stale-issues.yml b/.github/workflows/agent-close-stale-issues.yml new file mode 100644 index 0000000..7511ed9 --- /dev/null +++ b/.github/workflows/agent-close-stale-issues.yml @@ -0,0 +1,47 @@ +name: Agent / Close Stale Issues + +on: + schedule: + - cron: "0 9 * * *" + workflow_dispatch: + +permissions: + issues: write + +concurrency: + group: agent-close-stale-issues-${{ github.repository }} + cancel-in-progress: false + +jobs: + close: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + STALE_DAYS: "30" + steps: + - name: Close stale agent issues + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail + + cutoff="$(node -e 'const days = Number(process.env.STALE_DAYS || 30); const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000); console.log(cutoff.toISOString().slice(0, 10));')" + + gh issue list \ + --repo "$REPO" \ + --state open \ + --label agent \ + --search "updated:<$cutoff" \ + --limit 1000 \ + --json number \ + --jq '.[].number' | + while read -r issue; do + if [ -z "$issue" ]; then + continue + fi + + gh issue close "$issue" \ + --repo "$REPO" \ + --reason "not planned" \ + --comment "Closing because this agent issue has had no activity for ${STALE_DAYS} days." + done diff --git a/.github/workflows/agent-daily-summary.yml b/.github/workflows/agent-daily-summary.yml new file mode 100644 index 0000000..f755889 --- /dev/null +++ b/.github/workflows/agent-daily-summary.yml @@ -0,0 +1,236 @@ +name: Agent / Daily Summary + +on: + schedule: + - cron: "0 11 * * *" # Daily at 7 AM ET / 11 AM UTC + workflow_dispatch: + inputs: + lookback_days: + description: "How many days of repository activity to summarize" + required: false + default: "1" + discussion_category: + description: "Discussion category for posted summaries. Defaults to AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY or General." + required: false + default: "" + +permissions: + actions: read + contents: read + discussions: write + issues: read + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-daily-summary-${{ github.repository }} + cancel-in-progress: false + +jobs: + pre_gate: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + skip: ${{ steps.gate.outputs.skip }} + mode: ${{ steps.gate.outputs.mode }} + reason: ${{ steps.gate.outputs.reason }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve scheduled disabled gate + id: gate + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ github.token }} + schedule_policy: ${{ vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-daily-summary.yml + + signals: + needs: pre_gate + if: needs.pre_gate.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + DISCUSSION_CATEGORY: ${{ inputs.discussion_category || vars.AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY || 'General' }} + LOOKBACK_DAYS: ${{ inputs.lookback_days || '1' }} + outputs: + skip: ${{ steps.discussion_gate.outputs.skip == 'true' && 'true' || steps.gate.outputs.skip }} + mode: ${{ steps.gate.outputs.mode }} + reason: ${{ steps.discussion_gate.outputs.skip == 'true' && steps.discussion_gate.outputs.reason || steps.gate.outputs.reason }} + summary_date: ${{ steps.signals.outputs.summary_date }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve summary discussion gate + id: discussion_gate + uses: ./.github/actions/discussion-post-gate + with: + github_token: ${{ steps.auth.outputs.token }} + discussion_category: ${{ env.DISCUSSION_CATEGORY }} + + - name: Setup agent runtime for activity signals + if: steps.discussion_gate.outputs.skip != 'true' + uses: ./.github/actions/setup-agent-runtime + + - name: Gather repository signals + if: steps.discussion_gate.outputs.skip != 'true' + id: signals + shell: bash + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + REPO_SLUG: ${{ github.repository }} + run: | + set -euo pipefail + + signals_dir="${RUNNER_TEMP}/daily-signals" + rm -rf "${signals_dir}" + mkdir -p "${signals_dir}" + + summary_date="$(date -u +%Y-%m-%d)" + node .agent/dist/cli/memory/sync-github-artifacts.js \ + --dir "${signals_dir}/memory" \ + --repo "${REPO_SLUG}" \ + --lookback-days "${LOOKBACK_DAYS}" \ + > "${signals_dir}/github-sync.json" + + echo "signals_dir=${signals_dir}" >> "${GITHUB_OUTPUT}" + echo "summary_date=${summary_date}" >> "${GITHUB_OUTPUT}" + + - name: Count summary activity + if: steps.discussion_gate.outputs.skip != 'true' + id: activity + shell: bash + env: + DISCUSSION_COUNT: ${{ steps.signals.outputs.discussion_count || '0' }} + ISSUE_COUNT: ${{ steps.signals.outputs.issue_count || '0' }} + PULL_COUNT: ${{ steps.signals.outputs.pull_count || '0' }} + run: | + set -euo pipefail + count=$((ISSUE_COUNT + PULL_COUNT + DISCUSSION_COUNT)) + echo "count=${count}" >> "${GITHUB_OUTPUT}" + + - name: Resolve scheduled activity gate + if: steps.discussion_gate.outputs.skip != 'true' + id: gate + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ steps.auth.outputs.token }} + schedule_policy: ${{ vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-daily-summary.yml + activity_count: ${{ steps.activity.outputs.count }} + + - name: Upload summary signals + if: steps.discussion_gate.outputs.skip != 'true' && steps.gate.outputs.skip != 'true' + uses: actions/upload-artifact@v4 + with: + name: daily-summary-signals-${{ github.run_id }}-${{ github.run_attempt }} + path: ${{ steps.signals.outputs.signals_dir }}/ + retention-days: 1 + + daily-summary: + needs: signals + if: needs.signals.result == 'success' && needs.signals.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + DISCUSSION_CATEGORY: ${{ inputs.discussion_category || vars.AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY || 'General' }} + LOOKBACK_DAYS: ${{ inputs.lookback_days || '1' }} + SIGNALS_DIR: daily-signals + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Download summary signals + uses: actions/download-artifact@v4 + with: + name: daily-summary-signals-${{ github.run_id }}-${{ github.run_attempt }} + path: ${{ env.SIGNALS_DIR }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve daily summary provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: daily-summary + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup selected provider + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Generate daily summary + id: summary + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: daily-summary + route: answer + memory_mode_override: 'read-only' + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_policy: none + request_text: >- + Generate the daily repository summary for ${{ needs.signals.outputs.summary_date }} using a ${{ env.LOOKBACK_DAYS }} day lookback. Signal files are in ${{ env.SIGNALS_DIR }}. + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: '0' + target_url: ${{ github.server_url }}/${{ github.repository }} + reasoning_effort: medium + workflow: agent-daily-summary.yml + + - name: Create summary discussion + if: steps.summary.outcome == 'success' + env: + BODY_FILE: ${{ steps.summary.outputs.response_file }} + DISCUSSION_CATEGORY: ${{ env.DISCUSSION_CATEGORY }} + DISCUSSION_FOOTER: "*Generated by the agent-daily-summary workflow*" + DISCUSSION_TITLE: Daily Summary — ${{ needs.signals.outputs.summary_date }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + run: node .agent/dist/cli/create-discussion.js diff --git a/.github/workflows/agent-entrypoint.yml b/.github/workflows/agent-entrypoint.yml new file mode 100644 index 0000000..472c1f3 --- /dev/null +++ b/.github/workflows/agent-entrypoint.yml @@ -0,0 +1,63 @@ +name: Agent Entrypoint + +# Thin entry point for this repo. Wires triggers, runner labels, and secrets +# into the shared agent-router.yml portal workflow. Consumer repos use the +# same agent-router.yml with their own triggers and configuration. + +on: + issues: + types: [opened, edited] + issue_comment: + types: [created, edited] + pull_request: + types: [opened, edited] + pull_request_review_comment: + types: [created, edited] + pull_request_review: + types: [submitted] + discussion: + types: [created, edited] + discussion_comment: + types: [created, edited] + +permissions: + actions: write + contents: write + discussions: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: >- + agent-${{ github.repository }}-${{ + github.event.issue && 'issue' || + github.event.pull_request && 'pull_request' || + github.event.discussion && 'discussion' || + github.event_name + }}-${{ + github.event.issue.number || + github.event.pull_request.number || + github.event.discussion.number || + github.run_id + }} + cancel-in-progress: false + +jobs: + agent: + # Broad pre-filter: the real mention validation happens in extract-context.js + # inside agent-router.yml (boundary-aware, strips code blocks and quotes). + if: contains(toJSON(github.event), vars.AGENT_HANDLE || '@sepo-agent') + uses: ./.github/workflows/agent-router.yml + with: + agent_handle: ${{ vars.AGENT_HANDLE || '@sepo-agent' }} + runs_on: ${{ vars.AGENT_RUNS_ON || '["ubuntu-latest"]' }} + access_policy: ${{ vars.AGENT_ACCESS_POLICY || '' }} + automation_mode: ${{ vars.AGENT_AUTOMATION_MODE || 'agent' }} + automation_max_rounds: ${{ vars.AGENT_AUTOMATION_MAX_ROUNDS || '12' }} + secrets: + AGENT_APP_ID: ${{ secrets.AGENT_APP_ID }} + AGENT_APP_PRIVATE_KEY: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + AGENT_PAT: ${{ secrets.AGENT_PAT }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} diff --git a/.github/workflows/agent-fix-pr.yml b/.github/workflows/agent-fix-pr.yml new file mode 100644 index 0000000..e580925 --- /dev/null +++ b/.github/workflows/agent-fix-pr.yml @@ -0,0 +1,309 @@ +name: Agent / Fix PR + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to fix" + required: true + requested_by: + description: "GitHub login that approved the run" + required: false + approval_comment_url: + description: "Approval comment URL" + required: false + request_comment_id: + description: "ID of the triggering PR comment or review" + required: false + request_comment_url: + description: "URL of the triggering PR comment or review" + required: false + request_source_kind: + description: "Source kind that triggered the PR fix run" + required: false + request_text: + description: "Original user request text forwarded from the portal" + required: false + orchestrator_context: + description: "Planner-provided instructions from agent-orchestrator.yml for automated handoffs" + required: false + default: "" + session_bundle_mode: + description: "Session bundle persistence mode (defaults to repository variable AGENT_SESSION_BUNDLE_MODE or 'auto')" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + orchestration_enabled: + description: "Whether this run belongs to an explicit orchestrator chain" + required: false + default: "false" + workflow_call: + inputs: + pr_number: + type: string + required: true + requested_by: + type: string + required: false + approval_comment_url: + type: string + required: false + request_comment_id: + type: string + required: false + request_comment_url: + type: string + required: false + request_source_kind: + type: string + required: false + request_text: + type: string + required: false + orchestrator_context: + type: string + required: false + default: "" + runs_on: + type: string + default: "" + session_bundle_mode: + type: string + default: "" + automation_mode: + type: string + required: false + default: "disabled" + automation_current_round: + type: string + required: false + default: "1" + automation_max_rounds: + type: string + required: false + default: "12" + orchestration_enabled: + type: string + required: false + default: "false" + +permissions: + actions: write + contents: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-fix-pr-${{ inputs.pr_number }} + cancel-in-progress: false + +jobs: + fix-pr: + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MODEL_REASONING_EFFORT: xhigh + PR_NUMBER: ${{ inputs.pr_number }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve fix-pr provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: fix-pr + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Checkout PR head branch + id: pr + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + PR_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/checkout-pr.js + + - name: Label target pull request + if: vars.AGENT_STATUS_LABEL_ENABLED == 'true' && steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + continue-on-error: true + env: + AGENT_STATUS_LABEL_ENABLED: ${{ vars.AGENT_STATUS_LABEL_ENABLED || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/add-label.js + + - name: Resolve task timeout + if: steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: fix-pr + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run agent + if: steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + id: agent + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: fix-pr + route: fix-pr + lane: fix-pr-${{ steps.provider.outputs.provider }} + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: resume-best-effort + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + source_kind: ${{ inputs.request_source_kind || 'workflow_dispatch' }} + target_kind: pull_request + target_number: ${{ env.PR_NUMBER }} + target_url: ${{ github.server_url }}/${{ github.repository }}/pull/${{ env.PR_NUMBER }} + workflow: agent-fix-pr.yml + env: + REQUEST_COMMENT_ID: ${{ inputs.request_comment_id }} + REQUEST_COMMENT_URL: ${{ inputs.request_comment_url }} + REQUEST_SOURCE_KIND: ${{ inputs.request_source_kind || 'workflow_dispatch' }} + ORCHESTRATOR_CONTEXT: ${{ inputs.orchestrator_context }} + + - name: Detect PR branch head update + if: always() && steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + id: head + env: + ORIGINAL_HEAD_SHA: ${{ steps.pr.outputs.head_sha }} + run: node .agent/dist/cli/detect-head-change.js + + - name: Verify changes + if: always() && steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + id: verify + env: + HEAD_CHANGED: ${{ steps.head.outputs.head_changed }} + VERIFY_BASE_SHA: ${{ steps.pr.outputs.head_sha }} + run: node .agent/dist/cli/verify.js + + - name: Parse response + if: always() && steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + id: response + env: + AGENT_EXIT_CODE: ${{ steps.agent.outcome == 'success' && '0' || '1' }} + HAS_CHANGES: ${{ steps.verify.outputs.has_changes }} + HEAD_CHANGED: ${{ steps.head.outputs.head_changed }} + RESPONSE_FILE: ${{ steps.agent.outputs.response_file }} + VERIFY_EXIT_CODE: ${{ steps.verify.outputs.verify_exit_code }} + run: node .agent/dist/cli/parse-response.js + + - name: Commit and push to PR branch + if: steps.response.outputs.status == 'success' && steps.verify.outputs.has_changes == 'true' + id: commit + env: + BRANCH: ${{ steps.pr.outputs.head_ref }} + COMMIT_MESSAGE: >- + ${{ steps.response.outputs.commit_message || format('fix: address PR #{0} feedback ({1})', env.PR_NUMBER, steps.provider.outputs.provider) }} + GIT_BOT_EMAIL: ${{ vars.AGENT_COMMITTER_EMAIL || '' }} + GIT_BOT_NAME: ${{ vars.AGENT_COMMITTER_NAME || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + PUSH_LEASE_OID: ${{ steps.pr.outputs.head_sha }} + PUSH_REF: ${{ steps.pr.outputs.head_ref }} + run: node .agent/dist/cli/commit.js + + - name: Push PR branch head update + if: steps.response.outputs.status == 'success' && steps.verify.outputs.has_changes != 'true' && steps.head.outputs.head_changed == 'true' + id: push-head + env: + BRANCH: ${{ steps.pr.outputs.head_ref }} + EXPECTED_HEAD_SHA: ${{ steps.pr.outputs.head_sha }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: node .agent/dist/cli/push-pr-head.js + + - name: Post status comment + if: always() && steps.pr.outputs.cross_repo != 'true' && steps.pr.outputs.pr_state == 'OPEN' + env: + AGENT_COLLAPSE_OLD_REVIEWS: ${{ vars.AGENT_COLLAPSE_OLD_REVIEWS }} + APPROVAL_COMMENT_URL: ${{ inputs.approval_comment_url }} + BRANCH: ${{ steps.pr.outputs.head_ref }} + COMMENT_TARGET: pr + GH_TOKEN: ${{ steps.auth.outputs.token }} + PR_NUMBER: ${{ env.PR_NUMBER }} + REQUESTED_BY: ${{ inputs.orchestration_enabled == 'true' && (vars.AGENT_HANDLE || '@sepo-agent') || inputs.requested_by || github.actor }} + RESPONSE_FILE: ${{ steps.agent.outputs.response_file }} + RESUME_STATUS: ${{ steps.agent.outputs.resume_status }} + ROUTE: fix-pr + STATUS: ${{ (steps.commit.outcome == 'failure' || steps.push-head.outcome == 'failure') && 'failed' || steps.response.outputs.status || 'failed' }} + TARGET_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/post-comment.js + + - name: Post unsupported status + if: steps.pr.outputs.cross_repo == 'true' || steps.pr.outputs.pr_state != 'OPEN' + env: + AGENT_COLLAPSE_OLD_REVIEWS: ${{ vars.AGENT_COLLAPSE_OLD_REVIEWS }} + APPROVAL_COMMENT_URL: ${{ inputs.approval_comment_url }} + COMMENT_TARGET: pr + GH_TOKEN: ${{ steps.auth.outputs.token }} + ROUTE: fix-pr + STATUS: unsupported + TARGET_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/post-comment.js + + - name: Orchestrate automation handoff + if: >- + always() && + steps.pr.outputs.cross_repo != 'true' && + steps.pr.outputs.pr_state == 'OPEN' && + inputs.orchestration_enabled == 'true' + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ORCHESTRATION_ENABLED: ${{ inputs.orchestration_enabled }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: fix-pr + SOURCE_CONCLUSION: ${{ steps.response.outputs.status || 'failed' }} + TARGET_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js diff --git a/.github/workflows/agent-implement.yml b/.github/workflows/agent-implement.yml new file mode 100644 index 0000000..7a9c783 --- /dev/null +++ b/.github/workflows/agent-implement.yml @@ -0,0 +1,322 @@ +name: Agent / Implement + +on: + workflow_dispatch: + inputs: + issue_number: + description: "Issue number to implement" + required: true + requested_by: + description: "GitHub login that approved the run" + required: false + approval_comment_url: + description: "Approval comment URL" + required: false + request_text: + description: "Original user request text forwarded from the portal" + required: false + session_fork_from_thread_key: + description: "Optional source thread key used to seed this implementation session" + required: false + default: "" + session_bundle_mode: + description: "Session bundle persistence mode (defaults to repository variable AGENT_SESSION_BUNDLE_MODE or 'auto')" + required: false + default: "" + base_branch: + description: "Branch to base the implementation branch and PR on" + required: false + default: "" + base_pr: + description: "Open PR number whose same-repository head branch becomes the implementation base" + required: false + default: "" + implementation_route: + description: "Route identity for this implementation run" + required: false + default: implement + implementation_prompt: + description: "Prompt name for this implementation run" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + orchestration_enabled: + description: "Whether this run belongs to an explicit orchestrator chain" + required: false + default: "false" + workflow_call: + inputs: + issue_number: + type: string + required: true + requested_by: + type: string + required: false + approval_comment_url: + type: string + required: false + request_text: + type: string + required: false + session_fork_from_thread_key: + type: string + required: false + default: "" + session_bundle_mode: + type: string + required: false + default: "" + base_branch: + type: string + required: false + default: "" + base_pr: + type: string + required: false + default: "" + implementation_route: + type: string + required: false + default: implement + implementation_prompt: + type: string + required: false + default: "" + automation_mode: + type: string + required: false + default: "disabled" + automation_current_round: + type: string + required: false + default: "1" + automation_max_rounds: + type: string + required: false + default: "12" + orchestration_enabled: + type: string + required: false + default: "false" + runs_on: + type: string + default: "" + +permissions: + actions: write + contents: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-implement-${{ inputs.issue_number }} + cancel-in-progress: false + +jobs: + implement: + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + ISSUE_NUMBER: ${{ inputs.issue_number }} + IMPLEMENTATION_ROUTE: ${{ inputs.implementation_route || 'implement' }} + IMPLEMENTATION_PROMPT: ${{ inputs.implementation_prompt || inputs.implementation_route || 'implement' }} + MODEL_REASONING_EFFORT: xhigh + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve implementation provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: ${{ env.IMPLEMENTATION_ROUTE }} + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup branch name + run: echo "BRANCH=agent/${IMPLEMENTATION_ROUTE}-issue-${ISSUE_NUMBER}/${{ steps.provider.outputs.provider }}-${{ github.run_id }}" >> "$GITHUB_ENV" + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve implementation base + id: implementation_base + env: + BASE_BRANCH: ${{ inputs.base_branch }} + BASE_PR: ${{ inputs.base_pr }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: node .agent/dist/cli/resolve-implementation-base.js + + - name: Label source issue + if: vars.AGENT_STATUS_LABEL_ENABLED == 'true' + continue-on-error: true + env: + AGENT_STATUS_LABEL_ENABLED: ${{ vars.AGENT_STATUS_LABEL_ENABLED || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_KIND: issue + TARGET_NUMBER: ${{ env.ISSUE_NUMBER }} + run: node .agent/dist/cli/add-label.js + + - name: Create implementation branch + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + run: | + set -euo pipefail + AUTH_HEADER="$(node -e "process.stdout.write(Buffer.from('x-access-token:' + process.env.GH_TOKEN).toString('base64'))")" + git -c "http.${GITHUB_SERVER_URL}/.extraheader=AUTHORIZATION: basic ${AUTH_HEADER}" fetch origin "refs/heads/${BASE_BRANCH}" + git checkout -b "${BRANCH}" FETCH_HEAD + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: ${{ env.IMPLEMENTATION_ROUTE }} + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run agent + id: agent + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: ${{ env.IMPLEMENTATION_PROMPT }} + route: ${{ env.IMPLEMENTATION_ROUTE }} + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_fork_from_thread_key: ${{ inputs.session_fork_from_thread_key }} + session_policy: ${{ inputs.session_fork_from_thread_key != '' && 'resume-best-effort' || 'track-only' }} + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + target_kind: issue + target_number: ${{ env.ISSUE_NUMBER }} + target_url: ${{ github.server_url }}/${{ github.repository }}/issues/${{ env.ISSUE_NUMBER }} + workflow: agent-implement.yml + + - name: Verify changes + if: always() + id: verify + run: node .agent/dist/cli/verify.js + + - name: Parse response + if: always() + id: response + env: + AGENT_EXIT_CODE: ${{ steps.agent.outcome == 'success' && '0' || '1' }} + HAS_CHANGES: ${{ steps.verify.outputs.has_changes }} + RESPONSE_FILE: ${{ steps.agent.outputs.response_file }} + VERIFY_EXIT_CODE: ${{ steps.verify.outputs.verify_exit_code }} + run: node .agent/dist/cli/parse-response.js + + - name: Commit and push + if: steps.response.outputs.status == 'success' + id: commit + env: + BRANCH: ${{ env.BRANCH }} + COMMIT_MESSAGE: >- + ${{ steps.response.outputs.commit_message || format('feat: agent-{0} #{1} ({2})', env.IMPLEMENTATION_ROUTE, env.ISSUE_NUMBER, steps.provider.outputs.provider) }} + GIT_BOT_EMAIL: ${{ vars.AGENT_COMMITTER_EMAIL || '' }} + GIT_BOT_NAME: ${{ vars.AGENT_COMMITTER_NAME || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + SET_UPSTREAM: "true" + run: node .agent/dist/cli/commit.js + + - name: Create pull request + if: steps.commit.outputs.committed == 'true' + id: pr + env: + BASE_BRANCH: ${{ env.BASE_BRANCH }} + BRANCH: ${{ env.BRANCH }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }} + PR_BODY: ${{ steps.response.outputs.pr_body }} + PR_TITLE: ${{ steps.response.outputs.pr_title }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + run: node .agent/dist/cli/create-pr.js + + - name: Label generated pull request + if: steps.pr.outputs.pr_number != '' && vars.AGENT_STATUS_LABEL_ENABLED == 'true' + continue-on-error: true + env: + AGENT_STATUS_LABEL_ENABLED: ${{ vars.AGENT_STATUS_LABEL_ENABLED || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ steps.pr.outputs.pr_number }} + run: node .agent/dist/cli/add-label.js + + - name: Post status comment + if: always() + env: + APPROVAL_COMMENT_URL: ${{ inputs.approval_comment_url }} + BRANCH: ${{ env.BRANCH }} + COMMENT_TARGET: issue + GH_TOKEN: ${{ steps.auth.outputs.token }} + ISSUE_NUMBER: ${{ env.ISSUE_NUMBER }} + PR_URL: ${{ steps.pr.outputs.pr_url }} + RESPONSE_FILE: ${{ steps.agent.outputs.response_file }} + RESUME_STATUS: ${{ steps.agent.outputs.resume_status }} + ROUTE: ${{ env.IMPLEMENTATION_ROUTE }} + STATUS: ${{ steps.response.outputs.status || 'failed' }} + TARGET_NUMBER: ${{ env.ISSUE_NUMBER }} + run: node .agent/dist/cli/post-comment.js + + - name: Orchestrate automation handoff + if: >- + always() && + steps.auth.outputs.token && + inputs.orchestration_enabled == 'true' + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + NEXT_TARGET_NUMBER: ${{ steps.pr.outputs.pr_number }} + ORCHESTRATION_ENABLED: ${{ inputs.orchestration_enabled }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: implement + SOURCE_CONCLUSION: ${{ steps.response.outputs.status || 'failed' }} + TARGET_NUMBER: ${{ env.ISSUE_NUMBER }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js diff --git a/.github/workflows/agent-label.yml b/.github/workflows/agent-label.yml new file mode 100644 index 0000000..22c07dc --- /dev/null +++ b/.github/workflows/agent-label.yml @@ -0,0 +1,96 @@ +name: Agent Label + +on: + issues: + types: [labeled] + pull_request_target: + types: [labeled] + +permissions: + actions: write + contents: write + discussions: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: >- + agent-${{ github.repository }}-${{ + github.event.issue && 'issue' || + github.event.pull_request && 'pull_request' || + github.event_name + }}-${{ + github.event.issue.number || + github.event.pull_request.number || + github.run_id + }} + cancel-in-progress: false + +jobs: + agent: + if: startsWith(github.event.label.name, 'agent/') + uses: ./.github/workflows/agent-router.yml + with: + runs_on: ${{ vars.AGENT_RUNS_ON || '["ubuntu-latest"]' }} + access_policy: ${{ vars.AGENT_ACCESS_POLICY || '' }} + automation_mode: ${{ vars.AGENT_AUTOMATION_MODE || 'agent' }} + automation_max_rounds: ${{ vars.AGENT_AUTOMATION_MAX_ROUNDS || '12' }} + trigger_kind: label + label_name: ${{ github.event.label.name }} + secrets: + AGENT_APP_ID: ${{ secrets.AGENT_APP_ID }} + AGENT_APP_PRIVATE_KEY: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + AGENT_PAT: ${{ secrets.AGENT_PAT }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} + CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + cleanup-label: + needs: agent + if: >- + needs.agent.result == 'success' && + needs.agent.outputs.should_respond == 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - uses: actions/github-script@v7 + with: + github-token: ${{ steps.auth.outputs.token }} + script: | + const issueNumber = + context.payload.issue?.number ?? + context.payload.pull_request?.number; + const labelName = context.payload.label?.name; + + if (!issueNumber || !labelName) { + core.setFailed("Missing issue_number or label_name for cleanup"); + return; + } + + try { + await github.rest.issues.removeLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issueNumber, + name: labelName, + }); + core.info(`Removed trigger label ${labelName} from #${issueNumber}.`); + } catch (error) { + if (error && typeof error === 'object' && 'status' in error && error.status === 404) { + core.info(`Trigger label ${labelName} was already absent from #${issueNumber}.`); + return; + } + throw error; + } diff --git a/.github/workflows/agent-memory-bootstrap.yml b/.github/workflows/agent-memory-bootstrap.yml new file mode 100644 index 0000000..f160a9f --- /dev/null +++ b/.github/workflows/agent-memory-bootstrap.yml @@ -0,0 +1,199 @@ +name: Agent / Memory / Initialization + +on: + workflow_dispatch: + inputs: + memory_ref: + description: "Memory branch to create on first run" + required: false + default: agent/memory + +permissions: + contents: write + discussions: read + issues: read + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-memory-${{ github.repository }}-bootstrap + cancel-in-progress: false + +jobs: + bootstrap: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MEMORY_REF: ${{ inputs.memory_ref || vars.AGENT_MEMORY_REF || 'agent/memory' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve memory bootstrap provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: memory-bootstrap + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Reject existing memory branch + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: | + set -euo pipefail + refs_file="$(mktemp)" + trap 'rm -f "$refs_file"' EXIT + gh api "repos/${GITHUB_REPOSITORY}/git/matching-refs/heads/${MEMORY_REF}" --jq '.[].ref' >"$refs_file" + exact_ref="refs/heads/${MEMORY_REF}" + if grep -Fxq "$exact_ref" "$refs_file"; then + echo "Memory branch ${GITHUB_REPOSITORY}@${MEMORY_REF} already exists. Bootstrap is first-run only." >&2 + exit 1 + fi + + - name: Download memory branch + id: memory + uses: ./.github/actions/download-agent-memory + with: + github_token: ${{ steps.auth.outputs.token }} + ref: ${{ env.MEMORY_REF }} + path: ${{ runner.temp }}/agent-memory + continue_on_missing: "true" + bootstrap_if_missing: "true" + + - name: Commit and push memory branch + id: commit + working-directory: ${{ runner.temp }}/agent-memory + env: + BRANCH: ${{ env.MEMORY_REF }} + COMMIT_CWD: ${{ runner.temp }}/agent-memory + COMMIT_MESSAGE: "chore(memory): initialize memory branch" + GITHUB_REPOSITORY: ${{ github.repository }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + SET_UPSTREAM: "true" + run: node ${{ github.workspace }}/.agent/dist/cli/commit.js + + - name: Read memory sync state + if: steps.memory.outputs.memory_available == 'true' + id: state + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + run: node .agent/dist/cli/memory/read-sync-state.js + + - name: Resolve sync window + if: steps.memory.outputs.memory_available == 'true' + id: window + env: + LOOKBACK_DAYS: "30" + PREVIOUS_LAST_SYNC: "" + SINCE_OVERRIDE: "" + run: | + set -euo pipefail + started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + if [ -n "$SINCE_OVERRIDE" ]; then + since="$SINCE_OVERRIDE" + elif [ -n "$PREVIOUS_LAST_SYNC" ]; then + since="$PREVIOUS_LAST_SYNC" + else + since="" + fi + echo "started_at=$started_at" >> "$GITHUB_OUTPUT" + echo "since=$since" >> "$GITHUB_OUTPUT" + + - name: Sync GitHub artifacts into memory + if: steps.memory.outputs.memory_available == 'true' + id: sync + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + MEMORY_DIR: ${{ runner.temp }}/agent-memory + MEMORY_SYNC_LOOKBACK_DAYS: "30" + MEMORY_SYNC_SINCE: ${{ steps.window.outputs.since }} + MEMORY_SYNC_STARTED_AT: ${{ steps.window.outputs.started_at }} + REPO_SLUG: ${{ github.repository }} + run: node .agent/dist/cli/memory/sync-github-artifacts.js + + - name: Commit and push synced memory artifacts + if: steps.sync.outcome == 'success' + working-directory: ${{ runner.temp }}/agent-memory + env: + BRANCH: ${{ env.MEMORY_REF }} + COMMIT_CWD: ${{ runner.temp }}/agent-memory + COMMIT_MESSAGE: "chore(memory): sync github artifacts" + GITHUB_REPOSITORY: ${{ github.repository }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + SET_UPSTREAM: "true" + run: node ${{ github.workspace }}/.agent/dist/cli/commit.js + + - name: Write memory sync state + if: steps.sync.outcome == 'success' + env: + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + REPO_SLUG: ${{ github.repository }} + SYNC_COMMIT_CURSOR: ${{ steps.sync.outputs.commit_cursor }} + SYNC_DISCUSSION_CURSOR: ${{ steps.sync.outputs.discussion_cursor }} + SYNC_ISSUE_CURSOR: ${{ steps.sync.outputs.issue_cursor }} + SYNC_LAST_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + SYNC_LAST_SYNC_AT: ${{ steps.window.outputs.started_at }} + SYNC_PULL_CURSOR: ${{ steps.sync.outputs.pull_cursor }} + run: node .agent/dist/cli/memory/write-sync-state.js + + - name: Resolve task timeout + if: steps.sync.outcome == 'success' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Curate memory from recent activity + if: steps.sync.outcome == 'success' + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: memory-scan + route: answer + memory_mode_override: 'enabled' + memory_ref: ${{ env.MEMORY_REF }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_policy: none + request_text: >- + Initial memory bootstrap. Curate durable memory from recent repository activity after the initial GitHub artifact mirror; skip anything not worth carrying forward. + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: '0' + target_url: ${{ github.server_url }}/${{ github.repository }} + reasoning_effort: medium + workflow: agent-memory-bootstrap.yml diff --git a/.github/workflows/agent-memory-pr-closed.yml b/.github/workflows/agent-memory-pr-closed.yml new file mode 100644 index 0000000..c7ff854 --- /dev/null +++ b/.github/workflows/agent-memory-pr-closed.yml @@ -0,0 +1,104 @@ +name: Agent / Memory / Record PR Closure + +on: + pull_request_target: + types: [closed] + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to record in memory" + required: true + memory_ref: + description: "Memory branch to update" + required: false + default: agent/memory + +permissions: + contents: write + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-memory-${{ github.repository }}-pr-${{ github.event.pull_request.number || inputs.pr_number || github.run_id }} + cancel-in-progress: false + +jobs: + record: + # Fork safety: run automatically only for same-repo PRs or merged fork PRs + # (a deliberate post-merge trust trade-off). Merged fork PR metadata can + # still be attacker-controlled and edited after merge; v3 accepts that risk + # for memory curation. Skip closed-without-merge fork PRs where attacker- + # controlled title/body would reach the LLM without merge review. + if: >- + github.event_name == 'workflow_dispatch' || + github.event.pull_request.head.repo.full_name == github.repository || + github.event.pull_request.merged == true + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MEMORY_REF: ${{ inputs.memory_ref || vars.AGENT_MEMORY_REF || 'agent/memory' }} + PR_NUMBER: ${{ inputs.pr_number || github.event.pull_request.number }} + PR_URL: ${{ github.event.pull_request.html_url || format('{0}/{1}/pull/{2}', github.server_url, github.repository, inputs.pr_number) }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve memory PR closure provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: memory-pr-closed + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Record PR closure into memory + id: summarize + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: memory-pr-closed + route: answer + memory_mode_override: 'enabled' + memory_ref: ${{ env.MEMORY_REF }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_policy: none + request_text: >- + Record this closed pull request in repository memory. One daily bullet, plus durable memory updates only if warranted. + requested_by: ${{ github.actor }} + source_kind: pull_request + target_kind: pull_request + target_number: ${{ env.PR_NUMBER }} + target_url: ${{ env.PR_URL }} + reasoning_effort: medium + workflow: agent-memory-pr-closed.yml diff --git a/.github/workflows/agent-memory-scan.yml b/.github/workflows/agent-memory-scan.yml new file mode 100644 index 0000000..a27961d --- /dev/null +++ b/.github/workflows/agent-memory-scan.yml @@ -0,0 +1,133 @@ +name: Agent / Memory / Curate Recent Activity + +on: + schedule: + - cron: '0 */6 * * *' + workflow_dispatch: + inputs: + memory_ref: + description: "Memory branch to update" + required: false + default: agent/memory + +permissions: + contents: write + issues: read + pull-requests: read + discussions: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-memory-${{ github.repository }}-scan + cancel-in-progress: false + +jobs: + gate: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + skip: ${{ steps.gate.outputs.skip }} + mode: ${{ steps.gate.outputs.mode }} + reason: ${{ steps.gate.outputs.reason }} + dependency_value: ${{ steps.gate.outputs.dependency_value }} + self_value: ${{ steps.gate.outputs.self_value }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve scheduled activity gate + id: gate + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ github.token }} + schedule_policy: ${{ vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-memory-scan.yml + dependency_ref: refs/agent-memory-state/sync + dependency_field: last_activity_at + self_ref: refs/agent-memory-state/scan + self_field: last_scan_at + + scan: + needs: gate + if: needs.gate.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MEMORY_REF: ${{ inputs.memory_ref || vars.AGENT_MEMORY_REF || 'agent/memory' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve memory scan provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: memory-scan + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Curate memory from recent activity + id: scan + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: memory-scan + route: answer + memory_mode_override: 'enabled' + memory_ref: ${{ env.MEMORY_REF }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_policy: none + request_text: >- + Scheduled memory maintenance. Curate durable memory from recent repository activity; skip anything not worth carrying forward. + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: '0' + target_url: ${{ github.server_url }}/${{ github.repository }} + reasoning_effort: medium + workflow: agent-memory-scan.yml + + - name: Write memory scan state + if: steps.scan.outcome == 'success' + env: + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + REPO_SLUG: ${{ github.repository }} + SCHEDULE_LAST_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + SCHEDULE_STATE_FIELD: last_scan_at + SCHEDULE_STATE_REF: refs/agent-memory-state/scan + run: node .agent/dist/cli/write-scheduled-state.js diff --git a/.github/workflows/agent-memory-sync.yml b/.github/workflows/agent-memory-sync.yml new file mode 100644 index 0000000..dce9074 --- /dev/null +++ b/.github/workflows/agent-memory-sync.yml @@ -0,0 +1,158 @@ +name: Agent / Memory / Sync GitHub Artifacts + +on: + workflow_dispatch: + inputs: + since: + description: "Optional ISO timestamp override for the sync window" + required: false + default: "" + lookback_days: + description: "Fallback lookback window in days when no prior sync state exists" + required: false + default: "30" + memory_ref: + description: "Memory branch to update" + required: false + default: agent/memory + schedule: + - cron: "17 */6 * * *" + +permissions: + contents: write + discussions: read + issues: read + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-memory-${{ github.repository }}-sync + cancel-in-progress: false + +jobs: + gate: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + skip: ${{ steps.gate.outputs.skip }} + mode: ${{ steps.gate.outputs.mode }} + reason: ${{ steps.gate.outputs.reason }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve scheduled activity gate + id: gate + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ github.token }} + schedule_policy: ${{ vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-memory-sync.yml + + sync: + needs: gate + if: needs.gate.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MEMORY_REF: ${{ inputs.memory_ref || vars.AGENT_MEMORY_REF || 'agent/memory' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Read memory sync state + id: state + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + run: node .agent/dist/cli/memory/read-sync-state.js + + - name: Resolve sync window + id: window + env: + LOOKBACK_DAYS: ${{ inputs.lookback_days || '30' }} + PREVIOUS_LAST_SYNC: ${{ steps.state.outputs.last_sync_at }} + SINCE_OVERRIDE: ${{ inputs.since || '' }} + run: | + set -euo pipefail + started_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + if [ -n "$SINCE_OVERRIDE" ]; then + since="$SINCE_OVERRIDE" + elif [ -n "$PREVIOUS_LAST_SYNC" ]; then + since="$PREVIOUS_LAST_SYNC" + else + since="" + fi + echo "started_at=$started_at" >> "$GITHUB_OUTPUT" + echo "since=$since" >> "$GITHUB_OUTPUT" + + - name: Download memory branch + id: memory + uses: ./.github/actions/download-agent-memory + with: + github_token: ${{ steps.auth.outputs.token }} + ref: ${{ env.MEMORY_REF }} + path: ${{ runner.temp }}/agent-memory + continue_on_missing: "true" + bootstrap_if_missing: "true" + + - name: Sync GitHub artifacts into memory + id: sync + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + MEMORY_DIR: ${{ runner.temp }}/agent-memory + MEMORY_SYNC_LOOKBACK_DAYS: ${{ inputs.lookback_days || '30' }} + MEMORY_SYNC_SINCE: ${{ steps.window.outputs.since }} + MEMORY_SYNC_STARTED_AT: ${{ steps.window.outputs.started_at }} + REPO_SLUG: ${{ github.repository }} + run: node .agent/dist/cli/memory/sync-github-artifacts.js + + - name: Commit and push memory branch + if: steps.sync.outcome == 'success' + working-directory: ${{ runner.temp }}/agent-memory + env: + BRANCH: ${{ env.MEMORY_REF }} + COMMIT_CWD: ${{ runner.temp }}/agent-memory + COMMIT_MESSAGE: "chore(memory): sync github artifacts" + GITHUB_REPOSITORY: ${{ github.repository }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + SET_UPSTREAM: "true" + run: node ${{ github.workspace }}/.agent/dist/cli/commit.js + + - name: Write memory sync state + if: steps.sync.outcome == 'success' + env: + GITHUB_REPOSITORY: ${{ github.repository }} + INPUT_GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + REPO_SLUG: ${{ github.repository }} + SYNC_COMMIT_CURSOR: ${{ steps.sync.outputs.commit_cursor }} + SYNC_DISCUSSION_CURSOR: ${{ steps.sync.outputs.discussion_cursor }} + SYNC_ISSUE_CURSOR: ${{ steps.sync.outputs.issue_cursor }} + SYNC_LAST_ACTIVITY_AT: ${{ steps.sync.outputs.last_activity_at }} + SYNC_LAST_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + SYNC_LAST_SYNC_AT: ${{ steps.window.outputs.started_at }} + SYNC_PULL_CURSOR: ${{ steps.sync.outputs.pull_cursor }} + run: node .agent/dist/cli/memory/write-sync-state.js diff --git a/.github/workflows/agent-onboarding.yml b/.github/workflows/agent-onboarding.yml new file mode 100644 index 0000000..4088a0e --- /dev/null +++ b/.github/workflows/agent-onboarding.yml @@ -0,0 +1,69 @@ +name: Agent / Onboarding / Check Setup + +on: + workflow_dispatch: + inputs: + memory_ref: + description: "Memory branch to check" + required: false + rubrics_ref: + description: "Rubrics branch to check" + required: false + +permissions: + contents: read + issues: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-onboarding-${{ github.repository }} + cancel-in-progress: false + +jobs: + check: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + MEMORY_REF: ${{ inputs.memory_ref || vars.AGENT_MEMORY_REF || 'agent/memory' }} + RUBRICS_REF: ${{ inputs.rubrics_ref || vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + steps: + - uses: actions/checkout@v4 + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve agent provider readiness + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: onboarding + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + required: "false" + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: "false" + install_claude: "false" + + - name: Create or update onboarding issue + id: onboarding + env: + AUTH_MODE: ${{ steps.auth.outputs.auth_mode }} + AGENT_PROVIDER: ${{ steps.provider.outputs.provider }} + AGENT_PROVIDER_REASON: ${{ steps.provider.outputs.reason }} + CLAUDE_CODE_OAUTH_TOKEN_CONFIGURED: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + MEMORY_REF: ${{ env.MEMORY_REF }} + OPENAI_API_KEY_CONFIGURED: ${{ secrets.OPENAI_API_KEY != '' }} + RUBRICS_REF: ${{ env.RUBRICS_REF }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: node .agent/dist/cli/onboarding-check.js diff --git a/.github/workflows/agent-orchestrator.yml b/.github/workflows/agent-orchestrator.yml new file mode 100644 index 0000000..e25ab5a --- /dev/null +++ b/.github/workflows/agent-orchestrator.yml @@ -0,0 +1,223 @@ +name: Agent / Orchestrator + +on: + workflow_dispatch: + inputs: + source_action: + description: "Agent action that handed back to the orchestrator" + required: true + source_conclusion: + description: "Normalized source action conclusion" + required: true + source_recommended_next_step: + description: "Optional source action recommended next step" + required: false + default: "" + source_run_id: + description: "Workflow run ID of the source action, used for handoff dedupe" + required: false + default: "" + target_number: + description: "Issue or pull request number currently being handled" + required: true + target_kind: + description: "Issue or pull request kind currently being handled" + required: false + default: "" + author_association: + description: "Original requester author association from router context" + required: false + default: "" + access_policy: + description: "Route access policy JSON used by router authorization" + required: false + default: "" + repository_private: + description: "Repository visibility flag for access policy defaults" + required: false + default: "" + next_target_number: + description: "Optional next target number produced by the source action" + required: false + default: "" + source_handoff_context: + description: "Optional action-oriented context derived by the source action" + required: false + default: "" + requested_by: + description: "GitHub login that requested the original run" + required: false + request_text: + description: "Original user request text forwarded from the source action" + required: false + session_bundle_mode: + description: "Session bundle persistence mode" + required: false + default: "" + base_branch: + description: "Branch to pass to agent-implement when dispatching an implementation" + required: false + default: "" + base_pr: + description: "Open PR number whose head branch agent-implement should stack on" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + +permissions: + actions: write + contents: read + issues: write + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-orchestrator-${{ github.repository }}-${{ inputs.target_number }}-${{ inputs.source_action }}-${{ inputs.automation_current_round }} + cancel-in-progress: false + +jobs: + orchestrate: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Check handoff preflight + id: preflight + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + SOURCE_ACTION: ${{ inputs.source_action }} + SOURCE_CONCLUSION: ${{ inputs.source_conclusion }} + TARGET_KIND: ${{ inputs.target_kind || (inputs.source_action == 'implement' && 'issue' || 'pull_request') }} + AGENT_ALLOW_SELF_APPROVE: ${{ vars.AGENT_ALLOW_SELF_APPROVE || 'false' }} + AGENT_ALLOW_SELF_MERGE: ${{ vars.AGENT_ALLOW_SELF_MERGE || 'false' }} + AUTHOR_ASSOCIATION: ${{ inputs.author_association }} + ACCESS_POLICY: ${{ inputs.access_policy }} + REPOSITORY_PRIVATE: ${{ inputs.repository_private || (github.event.repository.private && 'true' || 'false') }} + run: node .agent/dist/cli/orchestrator-preflight.js + + - name: Resolve orchestrator provider + id: provider + if: ${{ steps.preflight.outputs.planner_enabled == 'true' }} + uses: ./.github/actions/resolve-agent-provider + with: + route: orchestrator + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Install orchestrator provider + if: ${{ steps.preflight.outputs.planner_enabled == 'true' }} + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + if: ${{ steps.preflight.outputs.planner_enabled == 'true' }} + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: orchestrator + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Plan next action with agent + id: planner + if: ${{ steps.preflight.outputs.planner_enabled == 'true' }} + continue-on-error: true + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + env: + ORCHESTRATOR_SOURCE_ACTION: ${{ inputs.source_action }} + ORCHESTRATOR_SOURCE_CONCLUSION: ${{ inputs.source_conclusion }} + ORCHESTRATOR_SOURCE_RECOMMENDED_NEXT_STEP: ${{ inputs.source_recommended_next_step }} + ORCHESTRATOR_SOURCE_RUN_ID: ${{ inputs.source_run_id || github.run_id }} + ORCHESTRATOR_NEXT_TARGET_NUMBER: ${{ inputs.next_target_number }} + ORCHESTRATOR_SOURCE_HANDOFF_CONTEXT: ${{ inputs.source_handoff_context }} + ORCHESTRATOR_SELF_APPROVE_ENABLED: ${{ vars.AGENT_ALLOW_SELF_APPROVE || 'false' }} + ORCHESTRATOR_SELF_MERGE_ENABLED: ${{ vars.AGENT_ALLOW_SELF_MERGE || 'false' }} + ORCHESTRATOR_CURRENT_ROUND: ${{ inputs.automation_current_round }} + ORCHESTRATOR_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: orchestrator + reasoning_effort: high + lane: planner + memory_mode_override: read-only + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_mode_override: read-only + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: resume-best-effort + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + route: orchestrator + source_kind: workflow_dispatch + target_kind: ${{ inputs.target_kind || (inputs.source_action == 'implement' && 'issue' || 'pull_request') }} + target_number: ${{ inputs.target_number }} + target_url: ${{ (inputs.target_kind || (inputs.source_action == 'implement' && 'issue' || 'pull_request')) == 'issue' && format('{0}/{1}/issues/{2}', github.server_url, github.repository, inputs.target_number) || format('{0}/{1}/pull/{2}', github.server_url, github.repository, inputs.target_number) }} + workflow: agent-orchestrator.yml + + - name: Decide and dispatch next action + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + AGENT_COLLAPSE_OLD_REVIEWS: ${{ vars.AGENT_COLLAPSE_OLD_REVIEWS }} + BASE_BRANCH: ${{ inputs.base_branch }} + BASE_PR: ${{ inputs.base_pr }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + NEXT_TARGET_NUMBER: ${{ inputs.next_target_number }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: ${{ inputs.source_action }} + SOURCE_CONCLUSION: ${{ inputs.source_conclusion }} + SOURCE_RECOMMENDED_NEXT_STEP: ${{ inputs.source_recommended_next_step }} + SOURCE_HANDOFF_CONTEXT: ${{ inputs.source_handoff_context }} + SOURCE_RUN_ID: ${{ inputs.source_run_id || github.run_id }} + AGENT_ALLOW_SELF_APPROVE: ${{ vars.AGENT_ALLOW_SELF_APPROVE || 'false' }} + AGENT_ALLOW_SELF_MERGE: ${{ vars.AGENT_ALLOW_SELF_MERGE || 'false' }} + AUTHOR_ASSOCIATION: ${{ inputs.author_association }} + ACCESS_POLICY: ${{ inputs.access_policy }} + REPOSITORY_PRIVATE: ${{ inputs.repository_private || (github.event.repository.private && 'true' || 'false') }} + TARGET_KIND: ${{ inputs.target_kind || (inputs.source_action == 'implement' && 'issue' || 'pull_request') }} + TARGET_NUMBER: ${{ inputs.target_number }} + PLANNER_RESPONSE_FILE: ${{ steps.planner.outputs.response_file }} + run: node .agent/dist/cli/orchestrate-handoff.js diff --git a/.github/workflows/agent-project-manager.yml b/.github/workflows/agent-project-manager.yml new file mode 100644 index 0000000..499754f --- /dev/null +++ b/.github/workflows/agent-project-manager.yml @@ -0,0 +1,213 @@ +name: Agent / Project Manager + +on: + schedule: + - cron: "17 */6 * * *" # Every 6 hours at minute 17 UTC + workflow_dispatch: + inputs: + enabled: + description: "Set true to run project management. Defaults off." + required: false + default: "false" + dry_run: + description: "Set false to allow label writes." + required: false + default: "true" + apply_labels: + description: "Set false to skip managed priority/effort label application." + required: false + default: "true" + post_summary: + description: "Set true to comment on today's Daily Summary discussion if it exists." + required: false + default: "false" + discussion_category: + description: "Discussion category where Daily Summary discussions are posted." + required: false + default: "General" + limit: + description: "Maximum open issues and PRs for the agent to inspect per kind." + required: false + default: "100" + +permissions: + contents: read + discussions: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-project-manager-${{ github.repository }} + cancel-in-progress: false + +jobs: + gate: + if: ${{ (github.event_name == 'workflow_dispatch' && inputs.enabled == 'true') || (github.event_name != 'workflow_dispatch' && vars.AGENT_PROJECT_MANAGEMENT_ENABLED == 'true') }} + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + skip: ${{ steps.gate.outputs.skip }} + mode: ${{ steps.gate.outputs.mode }} + reason: ${{ steps.gate.outputs.reason }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve scheduled activity gate + id: gate + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ github.token }} + schedule_policy: ${{ vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-project-manager.yml + + project-management: + needs: gate + if: needs.gate.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve project management configuration + id: project_config + shell: bash + env: + RAW_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || vars.AGENT_PROJECT_MANAGEMENT_DRY_RUN || 'true' }} + RAW_APPLY_LABELS: ${{ github.event_name == 'workflow_dispatch' && inputs.apply_labels || vars.AGENT_PROJECT_MANAGEMENT_APPLY_LABELS || 'true' }} + RAW_POST_SUMMARY: ${{ github.event_name == 'workflow_dispatch' && inputs.post_summary || vars.AGENT_PROJECT_MANAGEMENT_POST_SUMMARY || 'false' }} + RAW_DISCUSSION_CATEGORY: ${{ github.event_name == 'workflow_dispatch' && inputs.discussion_category || vars.AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY || 'General' }} + RAW_LIMIT: ${{ github.event_name == 'workflow_dispatch' && inputs.limit || vars.AGENT_PROJECT_MANAGEMENT_LIMIT || '100' }} + run: | + set -euo pipefail + + normalize_bool() { + local value="${1:-}" + local default="${2:-false}" + value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')" + if [ -z "$value" ]; then + echo "$default" + return + fi + case "$value" in + 1|true|yes|on) echo true ;; + *) echo false ;; + esac + } + + positive_int_or_default() { + local value="${1:-}" + local default="${2:-100}" + if printf '%s' "$value" | grep -Eq '^[1-9][0-9]*$'; then + echo "$value" + else + echo "$default" + fi + } + + dry_run="$(normalize_bool "$RAW_DRY_RUN" true)" + apply_labels="$(normalize_bool "$RAW_APPLY_LABELS" true)" + post_summary="$(normalize_bool "$RAW_POST_SUMMARY" false)" + discussion_category="${RAW_DISCUSSION_CATEGORY:-General}" + limit="$(positive_int_or_default "$RAW_LIMIT" 100)" + + { + echo "dry_run=${dry_run}" + echo "apply_labels=${apply_labels}" + echo "post_summary=${post_summary}" + echo "discussion_category=${discussion_category}" + echo "limit=${limit}" + } >> "$GITHUB_OUTPUT" + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve project manager provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: project-manager + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup selected provider + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run project manager agent + id: project_manager + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: project-manager + route: answer + memory_mode_override: disabled + rubrics_mode_override: disabled + session_policy: none + request_text: | + Run the scheduled project-manager pass for ${{ github.repository }}. + Configuration: + - repository: ${{ github.repository }} + - limit per kind: ${{ steps.project_config.outputs.limit }} + - dry run: ${{ steps.project_config.outputs.dry_run }} + - apply labels after agent: ${{ steps.project_config.outputs.apply_labels }} + - post summary after agent: ${{ steps.project_config.outputs.post_summary }} + - Daily Summary discussion category: ${{ steps.project_config.outputs.discussion_category }} + - workflow schedule: every 6 hours at minute 17 UTC + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: '0' + target_url: ${{ github.server_url }}/${{ github.repository }} + reasoning_effort: medium + workflow: agent-project-manager.yml + + - name: Apply managed label plan + id: managed_labels + env: + AGENT_PROJECT_MANAGEMENT_APPLY_LABELS: ${{ steps.project_config.outputs.apply_labels }} + AGENT_PROJECT_MANAGEMENT_DRY_RUN: ${{ steps.project_config.outputs.dry_run }} + BODY_FILE: ${{ steps.project_manager.outputs.response_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + run: node .agent/dist/cli/apply-project-management-labels.js + + - name: Publish project management summary + env: + AGENT_PROJECT_MANAGEMENT_DISCUSSION_CATEGORY: ${{ steps.project_config.outputs.discussion_category }} + AGENT_PROJECT_MANAGEMENT_POST_SUMMARY: ${{ steps.project_config.outputs.post_summary }} + BODY: ${{ steps.managed_labels.outputs.summary }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_TOKEN: ${{ steps.auth.outputs.token }} + run: node .agent/dist/cli/post-project-management-summary.js diff --git a/.github/workflows/agent-release-prepare.yml b/.github/workflows/agent-release-prepare.yml new file mode 100644 index 0000000..83359d1 --- /dev/null +++ b/.github/workflows/agent-release-prepare.yml @@ -0,0 +1,62 @@ +name: Agent / Release / Prepare + +on: + workflow_dispatch: + inputs: + version: + description: "Optional Sepo version to prepare, for example 0.2.0" + required: false + default: "" + +permissions: + actions: write + contents: read + issues: write + id-token: write # required for GitHub Actions OIDC broker exchange + +jobs: + prepare: + if: github.repository == 'self-evolving/repo' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: "false" + install_claude: "false" + + - name: Create or reuse release issue + id: release_issue + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REQUESTED_BY: ${{ github.actor }} + VERSION: ${{ inputs.version }} + run: node .agent/dist/cli/prepare-release.js + + - name: Dispatch implementation workflow + env: + APPROVAL_COMMENT_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + IMPLEMENTATION_PROMPT: agent-release + IMPLEMENTATION_ROUTE: implement + ISSUE_NUMBER: ${{ steps.release_issue.outputs.issue_number }} + REQUESTED_BY: ${{ github.actor }} + REQUEST_TEXT: ${{ steps.release_issue.outputs.request_text }} + run: node .agent/dist/cli/dispatch-agent-implement.js diff --git a/.github/workflows/agent-review.yml b/.github/workflows/agent-review.yml new file mode 100644 index 0000000..de89b73 --- /dev/null +++ b/.github/workflows/agent-review.yml @@ -0,0 +1,391 @@ +name: Agent / Review + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to review" + required: true + requested_by: + description: "GitHub login that requested the run" + required: false + approval_comment_url: + description: "Approval comment URL" + required: false + request_text: + description: "Original user request text forwarded from the portal" + required: false + session_bundle_mode: + description: "Session bundle persistence mode (defaults to repository variable AGENT_SESSION_BUNDLE_MODE or 'auto')" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + orchestration_enabled: + description: "Whether this run belongs to an explicit orchestrator chain" + required: false + default: "false" + workflow_call: + inputs: + pr_number: + type: string + required: true + requested_by: + type: string + required: false + approval_comment_url: + type: string + required: false + request_text: + type: string + required: false + runs_on: + type: string + default: "" + session_bundle_mode: + type: string + default: "" + automation_mode: + type: string + required: false + default: "disabled" + automation_current_round: + type: string + required: false + default: "1" + automation_max_rounds: + type: string + required: false + default: "12" + orchestration_enabled: + type: string + required: false + default: "false" + +permissions: + actions: write + contents: read + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +jobs: + prepare: + permissions: + actions: read + contents: read + pull-requests: read + id-token: write + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + reviewed_head_sha: ${{ steps.capture.outputs.head_sha }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Capture reviewed head + id: capture + continue-on-error: true + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/capture-pr-head.js + + # One job definition, two parallel runs via matrix. + # Adding a third reviewer = one more matrix entry. + review: + # Ordering-only: capture the reviewed head before reviewer lanes when + # prepare succeeds. Reviewers still run without provenance if prepare fails. + needs: [prepare] + if: ${{ !cancelled() }} + # Reviewer lanes are best-effort; synthesis fails later if no lane uploads a review. + continue-on-error: true + permissions: + # Reviewer jobs stay read-only; memory writes happen only in synthesize + # (see memory_mode_override below and per-job permissions on synthesize). + actions: read + contents: read + pull-requests: write + id-token: write + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + strategy: + fail-fast: false + matrix: + include: + - agent: claude + permission_mode: approve-all + reasoning_effort: max + artifact_name: claude-review + lane: claude-review + - agent: codex + permission_mode: approve-all + reasoning_effort: xhigh + artifact_name: codex-review + lane: codex-review + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ matrix.agent == 'codex' && 'true' || 'false' }} + install_claude: ${{ matrix.agent == 'claude' && 'true' || 'false' }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: review + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run ${{ matrix.agent }} review + id: agent + continue-on-error: true + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ matrix.agent }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: ${{ matrix.permission_mode }} + prompt: review + reasoning_effort: ${{ matrix.reasoning_effort }} + lane: ${{ matrix.lane }} + memory_mode_override: 'read-only' + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: track-only + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + route: review + source_kind: workflow_dispatch + target_kind: pull_request + target_number: ${{ inputs.pr_number }} + target_url: ${{ github.server_url }}/${{ github.repository }}/pull/${{ inputs.pr_number }} + workflow: agent-review.yml + + - name: Persist review artifacts + if: ${{ steps.agent.outcome == 'success' }} + run: | + set -euo pipefail + cp "${{ steps.agent.outputs.response_file }}" "${{ runner.temp }}/review.md" + printf '%s' "${{ steps.agent.outputs.acpx_session_id }}" > "${{ runner.temp }}/session.txt" + if [ -f "${{ steps.agent.outputs.session_log_file }}" ]; then + cp "${{ steps.agent.outputs.session_log_file }}" "${{ runner.temp }}/events.jsonl" + fi + + - uses: actions/upload-artifact@v4 + if: ${{ steps.agent.outcome == 'success' }} + with: + name: ${{ matrix.artifact_name }}-${{ inputs.pr_number }} + path: | + ${{ runner.temp }}/review.md + ${{ runner.temp }}/session.txt + ${{ runner.temp }}/events.jsonl + retention-days: 30 + + rubrics-review: + uses: ./.github/workflows/agent-rubrics-review.yml + with: + pr_number: ${{ inputs.pr_number }} + requested_by: ${{ inputs.requested_by || github.actor }} + request_text: ${{ inputs.request_text }} + runs_on: ${{ inputs.runs_on }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + post_comment: "true" + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + secrets: inherit + + synthesize: + needs: [prepare, review] + if: ${{ !cancelled() }} + permissions: + # Synthesize is the only review-path job that writes memory, so it's the + # only one that needs contents:write. Running after both reviewers + # also avoids the parallel-push race. + actions: write + contents: write + pull-requests: write + id-token: write + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Download review artifacts + continue-on-error: true + uses: actions/download-artifact@v4 + with: + path: ${{ runner.temp }}/reviews + + - name: Resolve review inputs + id: reviews + run: | + set -euo pipefail + + reviews_dir="${{ runner.temp }}/reviews" + mkdir -p "$reviews_dir" + + review_count=$(find "$reviews_dir" -type f -name review.md | wc -l | tr -d '[:space:]') + if [ "$review_count" = "0" ]; then + echo "No review.md files were produced by reviewer runs." >&2 + exit 1 + fi + + echo "reviews_dir=$reviews_dir" >> "$GITHUB_OUTPUT" + + - name: Resolve synthesis provider + id: synthesis_provider + uses: ./.github/actions/resolve-agent-provider + with: + route: review-synthesize + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.synthesis_provider.outputs.install_codex }} + install_claude: ${{ steps.synthesis_provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: review + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run synthesis + id: synthesis + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.synthesis_provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: review-synthesize + reasoning_effort: ${{ steps.synthesis_provider.outputs.provider == 'claude' && 'max' || 'xhigh' }} + lane: synthesize + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: track-only + requested_by: ${{ inputs.requested_by || github.actor }} + route: review + source_kind: workflow_dispatch + target_kind: pull_request + target_number: ${{ inputs.pr_number }} + target_url: ${{ github.server_url }}/${{ github.repository }}/pull/${{ inputs.pr_number }} + workflow: agent-review.yml + env: + REVIEWS_DIR: ${{ steps.reviews.outputs.reviews_dir }} + + - name: Post review comment + id: post_comment + env: + AGENT_COLLAPSE_OLD_REVIEWS: ${{ vars.AGENT_COLLAPSE_OLD_REVIEWS }} + APPROVAL_COMMENT_URL: ${{ inputs.approval_comment_url }} + COMMENT_TARGET: pr + GH_TOKEN: ${{ steps.auth.outputs.token }} + REQUESTED_BY: ${{ inputs.requested_by }} + RESPONSE_FILE: ${{ steps.synthesis.outputs.response_file }} + REVIEWED_HEAD_SHA: ${{ needs.prepare.outputs.reviewed_head_sha }} + ROUTE: review + STATUS: success + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/post-comment.js + + - uses: actions/upload-artifact@v4 + with: + name: agent-review-result-${{ inputs.pr_number }} + path: | + ${{ steps.synthesis.outputs.response_file }} + ${{ steps.synthesis.outputs.session_log_file }} + retention-days: 30 + + - name: Orchestrate automation handoff + if: >- + always() && + steps.auth.outputs.token && + steps.post_comment.outcome == 'success' && + inputs.orchestration_enabled == 'true' + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ORCHESTRATION_ENABLED: ${{ inputs.orchestration_enabled }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + # SOURCE_CONCLUSION is intentionally omitted for review; the dispatcher + # derives the verdict from the synthesis response file below. + RESPONSE_FILE: ${{ steps.synthesis.outputs.response_file }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: review + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js diff --git a/.github/workflows/agent-router.yml b/.github/workflows/agent-router.yml new file mode 100644 index 0000000..105e376 --- /dev/null +++ b/.github/workflows/agent-router.yml @@ -0,0 +1,831 @@ +name: Agent Router + +# Shared portal + routing workflow. +# +# This repo contains both the reusable workflows and the agent runtime. Template +# users are expected to duplicate the repository, then let setup-agent-runtime +# install dependencies and build the local runtime in place before agent steps +# run. +# +# Local usage (same repo): +# +# jobs: +# agent: +# uses: ./.github/workflows/agent-router.yml +# with: +# runs_on: ${{ vars.AGENT_RUNS_ON || '["ubuntu-latest"]' }} +# secrets: inherit + +on: + workflow_call: + outputs: + should_respond: + description: "Whether the portal accepted the trigger and handled routing" + value: ${{ jobs.portal.outputs.should_respond }} + inputs: + runs_on: + description: "Runner labels as JSON array (defaults to repository variable AGENT_RUNS_ON or '[\"ubuntu-latest\"]')" + type: string + required: false + default: "" + agent_handle: + description: "Mention handle for the agent (e.g. '@myorg/agent')" + type: string + default: "@sepo-agent" + default_agent: + description: "Default acpx agent provider (auto, codex, claude)" + type: string + default: auto + session_bundle_mode: + description: "Session bundle persistence mode for agent runs (defaults to repository variable AGENT_SESSION_BUNDLE_MODE or 'auto')" + type: string + default: "" + skill_root: + description: "Root directory for user-defined skills" + type: string + default: ".skills" + trigger_kind: + description: "Trigger surface mode (mention or label)" + type: string + default: mention + label_name: + description: "Raw triggering label when trigger_kind=label" + type: string + default: "" + author_association: + description: "Optional trusted association override" + type: string + default: "" + access_policy: + description: "Optional JSON access policy for trigger and route authorization" + type: string + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + type: string + default: "agent" + automation_max_rounds: + description: "Maximum automation handoff rounds" + type: string + default: "12" + secrets: + AGENT_APP_ID: + description: "GitHub App ID for elevated token" + required: false + AGENT_APP_PRIVATE_KEY: + description: "GitHub App private key" + required: false + AGENT_PAT: + description: "Fine-grained PAT or machine-user token" + required: false + OPENAI_API_KEY: + description: "OpenAI API key for Codex agent" + required: false + CLAUDE_CODE_OAUTH_TOKEN: + description: "Claude Code OAuth token" + required: false + +permissions: + actions: write + contents: write + discussions: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + # Note: workflow-level permissions are the union of all jobs. Individual + # agent invocations use route-specific acpx permission modes, with + # dispatch triage, explicit implement metadata generation, answer, + # implement, and fix-pr all currently using approve-all. + +jobs: + # --- Portal: extract context, triage, resolve route --- + portal: + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + should_respond: ${{ steps.context.outputs.should_respond }} + association: ${{ steps.context.outputs.association }} + body: ${{ steps.context.outputs.body }} + source_kind: ${{ steps.context.outputs.source_kind }} + target_kind: ${{ steps.context.outputs.target_kind }} + target_number: ${{ steps.context.outputs.target_number }} + target_url: ${{ steps.context.outputs.target_url }} + reaction_subject_id: ${{ steps.context.outputs.reaction_subject_id }} + response_kind: ${{ steps.context.outputs.response_kind }} + source_comment_id: ${{ steps.context.outputs.source_comment_id }} + source_comment_url: ${{ steps.context.outputs.source_comment_url }} + review_comment_id: ${{ steps.context.outputs.review_comment_id }} + discussion_node_id: ${{ steps.context.outputs.discussion_node_id }} + reply_to_id: ${{ steps.context.outputs.reply_to_id }} + requested_by: ${{ steps.context.outputs.requested_by }} + requested_route: ${{ steps.context.outputs.requested_route }} + requested_skill: ${{ steps.context.outputs.requested_skill }} + route: ${{ steps.dispatch.outputs.route }} + needs_approval: ${{ steps.dispatch.outputs.needs_approval }} + confidence: ${{ steps.dispatch.outputs.confidence }} + summary: ${{ steps.dispatch.outputs.summary }} + issue_title: ${{ steps.dispatch.outputs.issue_title }} + issue_body: ${{ steps.dispatch.outputs.issue_body }} + skill: ${{ steps.dispatch.outputs.skill }} + base_pr: ${{ steps.dispatch.outputs.base_pr }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve dispatch provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: dispatch + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || inputs.default_agent || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + required: "false" + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Extract context + id: context + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + INPUT_MENTION: ${{ inputs.agent_handle }} + INPUT_TRIGGER_KIND: ${{ inputs.trigger_kind }} + INPUT_LABEL_NAME: ${{ inputs.label_name }} + INPUT_AUTHOR_ASSOCIATION: ${{ inputs.author_association }} + run: node .agent/dist/cli/extract-context.js + + - name: React with eyes + if: steps.context.outputs.should_respond == 'true' + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + REACTION_SUBJECT_ID: ${{ steps.context.outputs.reaction_subject_id }} + REACTION_CONTENT: EYES + run: node .agent/dist/cli/add-reaction.js + + - name: Resolve explicit route authorization + if: >- + steps.context.outputs.should_respond == 'true' && + steps.context.outputs.requested_route == 'implement' && + steps.context.outputs.target_kind != 'issue' + id: explicit_dispatch + env: + REQUESTED_ROUTE: ${{ steps.context.outputs.requested_route }} + REQUESTED_SKILL: ${{ steps.context.outputs.requested_skill }} + REQUEST_TEXT: ${{ steps.context.outputs.body }} + TARGET_KIND: ${{ steps.context.outputs.target_kind }} + AUTHOR_ASSOCIATION: ${{ steps.context.outputs.association }} + ACCESS_POLICY: ${{ inputs.access_policy }} + REPOSITORY_PRIVATE: ${{ github.event.repository.private && 'true' || 'false' }} + run: node .agent/dist/cli/resolve-dispatch.js + + - name: Require dispatch provider + id: dispatch_provider + if: >- + steps.context.outputs.should_respond == 'true' && + steps.context.outputs.requested_route == '' + uses: ./.github/actions/resolve-agent-provider + with: + route: dispatch + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || inputs.default_agent || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Resolve task timeout + if: >- + steps.context.outputs.should_respond == 'true' && + ( + steps.context.outputs.requested_route == '' || + ( + steps.explicit_dispatch.outputs.route == 'implement' && + steps.context.outputs.target_kind != 'issue' && + steps.provider.outputs.provider != '' + ) + ) + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: dispatch + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run dispatch triage + if: >- + steps.context.outputs.should_respond == 'true' && + steps.context.outputs.requested_route == '' + id: triage + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.dispatch_provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: dispatch + route: dispatch + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: none + request_text: ${{ steps.context.outputs.body }} + requested_by: ${{ steps.context.outputs.requested_by }} + source_kind: ${{ steps.context.outputs.source_kind }} + target_kind: ${{ steps.context.outputs.target_kind }} + target_number: ${{ steps.context.outputs.target_number }} + target_url: ${{ steps.context.outputs.target_url }} + reasoning_effort: medium + workflow: agent-router.yml + + - name: Generate implement issue metadata + if: >- + steps.context.outputs.should_respond == 'true' && + steps.explicit_dispatch.outputs.route == 'implement' && + steps.context.outputs.target_kind != 'issue' && + steps.provider.outputs.provider != '' + id: implement_metadata + continue-on-error: true + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: agent-implement-metadata + route: dispatch + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: none + request_text: ${{ steps.context.outputs.body }} + requested_by: ${{ steps.context.outputs.requested_by }} + source_kind: ${{ steps.context.outputs.source_kind }} + target_kind: ${{ steps.context.outputs.target_kind }} + target_number: ${{ steps.context.outputs.target_number }} + target_url: ${{ steps.context.outputs.target_url }} + reasoning_effort: medium + workflow: agent-router.yml + + - name: Resolve route + if: steps.context.outputs.should_respond == 'true' + id: dispatch + env: + RESPONSE_FILE: ${{ steps.triage.outputs.response_file || steps.implement_metadata.outputs.response_file }} + REQUESTED_ROUTE: ${{ steps.context.outputs.requested_route }} + REQUESTED_SKILL: ${{ steps.context.outputs.requested_skill }} + REQUEST_TEXT: ${{ steps.context.outputs.body }} + TARGET_KIND: ${{ steps.context.outputs.target_kind }} + AUTHOR_ASSOCIATION: ${{ steps.context.outputs.association }} + ACCESS_POLICY: ${{ inputs.access_policy }} + REPOSITORY_PRIVATE: ${{ github.event.repository.private && 'true' || 'false' }} + run: node .agent/dist/cli/resolve-dispatch.js + + - name: Label handled issue or PR + if: >- + steps.context.outputs.should_respond == 'true' && + vars.AGENT_STATUS_LABEL_ENABLED == 'true' && + steps.dispatch.outputs.route != '' && + steps.dispatch.outputs.route != 'unsupported' && + (steps.context.outputs.target_kind == 'issue' || steps.context.outputs.target_kind == 'pull_request') + continue-on-error: true + env: + AGENT_STATUS_LABEL_ENABLED: ${{ vars.AGENT_STATUS_LABEL_ENABLED || '' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_KIND: ${{ steps.context.outputs.target_kind }} + TARGET_NUMBER: ${{ steps.context.outputs.target_number }} + run: node .agent/dist/cli/add-label.js + + - name: React with thumbs up (dispatch acknowledgment) + if: >- + steps.context.outputs.should_respond == 'true' && + (steps.dispatch.outputs.route == 'review' || steps.dispatch.outputs.route == 'fix-pr' || steps.dispatch.outputs.route == 'orchestrate') && + github.event.action != 'edited' + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + REACTION_SUBJECT_ID: ${{ steps.context.outputs.reaction_subject_id }} + REACTION_CONTENT: THUMBS_UP + run: node .agent/dist/cli/add-reaction.js + + # --- Route: answer (inline response) --- + answer: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + (needs.portal.outputs.route == 'answer' || needs.portal.outputs.route == 'unsupported') + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve answer provider + id: provider + if: needs.portal.outputs.route == 'answer' + uses: ./.github/actions/resolve-agent-provider + with: + route: answer + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || inputs.default_agent || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + id: runtime + if: >- + needs.portal.outputs.route == 'answer' || + needs.portal.outputs.route == 'unsupported' + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ needs.portal.outputs.route == 'answer' && steps.provider.outputs.install_codex || 'false' }} + install_claude: ${{ needs.portal.outputs.route == 'answer' && steps.provider.outputs.install_claude || 'false' }} + + - name: Resolve task timeout + if: needs.portal.outputs.route == 'answer' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: answer + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run answer agent + if: needs.portal.outputs.route == 'answer' + id: answer + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: answer + route: answer + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: resume-best-effort + request_text: ${{ needs.portal.outputs.body }} + requested_by: ${{ needs.portal.outputs.requested_by }} + source_kind: ${{ needs.portal.outputs.source_kind }} + target_kind: ${{ needs.portal.outputs.target_kind }} + target_number: ${{ needs.portal.outputs.target_number }} + target_url: ${{ needs.portal.outputs.target_url }} + reasoning_effort: high + workflow: agent-router.yml + + - name: Prepare unsupported response + if: needs.portal.outputs.route == 'unsupported' + env: + BODY_FILE: ${{ runner.temp }}/unsupported.md + SUMMARY: ${{ needs.portal.outputs.summary }} + run: printf '%s\n' "${SUMMARY}" > "${BODY_FILE}" + + - name: Post answer + if: needs.portal.outputs.route == 'answer' + env: + BODY_FILE: ${{ steps.answer.outputs.response_file }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + RESUME_STATUS: ${{ steps.answer.outputs.resume_status }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/post-response.js + + - name: Post unsupported response + if: needs.portal.outputs.route == 'unsupported' + env: + BODY_FILE: ${{ runner.temp }}/unsupported.md + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/post-response.js + + # --- Route: skill (inline response via <skill_root>/<name>/SKILL.md) --- + skill: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + needs.portal.outputs.route == 'skill' + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve skill provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: skill + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || inputs.default_agent || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + required: "false" + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Check skill + id: skill_check + uses: ./.github/actions/run-skill-setup + with: + skill: ${{ needs.portal.outputs.skill }} + skill_root: ${{ inputs.skill_root }} + trusted_ref: ${{ !startsWith(github.ref, 'refs/pull/') }} + run_setup: "false" + + - name: Post missing-skill comment + if: steps.skill_check.outputs.exists == 'false' + env: + BODY_FILE: ${{ runner.temp }}/missing-skill.md + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + REQUESTED_SKILL: ${{ needs.portal.outputs.skill }} + SKILL_PATH: ${{ steps.skill_check.outputs.skill_path }} + run: | + printf '%s\n' \ + "Skill \`${SKILL_PATH}\` was not found in this repository." \ + > "$BODY_FILE" + node .agent/dist/cli/post-response.js + + - name: Require skill provider + id: skill_provider + if: steps.skill_check.outputs.exists == 'true' + uses: ./.github/actions/resolve-agent-provider + with: + route: skill + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || inputs.default_agent || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Run skill setup + id: skill_setup + if: steps.skill_check.outputs.exists == 'true' + continue-on-error: true + uses: ./.github/actions/run-skill-setup + with: + skill: ${{ needs.portal.outputs.skill }} + skill_root: ${{ inputs.skill_root }} + trusted_ref: ${{ !startsWith(github.ref, 'refs/pull/') }} + run_setup: "true" + + - name: Post skill setup failure + if: steps.skill_setup.outcome == 'failure' + env: + BODY_FILE: ${{ runner.temp }}/skill-setup-failed.md + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + REQUESTED_SKILL: ${{ needs.portal.outputs.skill }} + SETUP_PATH: ${{ steps.skill_setup.outputs.setup_path }} + run: | + if [ -n "${SETUP_PATH}" ]; then + printf '%s\n' \ + "Skill setup failed for \`${REQUESTED_SKILL}\` using \`${SETUP_PATH}\`. Check the workflow logs for the failed setup step." \ + > "$BODY_FILE" + else + printf '%s\n' \ + "Skill setup failed for \`${REQUESTED_SKILL}\`. Check the workflow logs for the failed setup step." \ + > "$BODY_FILE" + fi + node .agent/dist/cli/post-response.js + + - name: Resolve task timeout + if: steps.skill_check.outputs.exists == 'true' && steps.skill_setup.outcome == 'success' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: skill + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run skill + id: skill + if: steps.skill_check.outputs.exists == 'true' && steps.skill_setup.outcome == 'success' + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.skill_provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + skill: ${{ needs.portal.outputs.skill }} + skill_root: ${{ inputs.skill_root }} + route: skill + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: none + request_text: ${{ needs.portal.outputs.body }} + requested_by: ${{ needs.portal.outputs.requested_by }} + source_kind: ${{ needs.portal.outputs.source_kind }} + target_kind: ${{ needs.portal.outputs.target_kind }} + target_number: ${{ needs.portal.outputs.target_number }} + target_url: ${{ needs.portal.outputs.target_url }} + reasoning_effort: high + workflow: agent-router.yml + + - name: Post skill response + if: steps.skill_check.outputs.exists == 'true' && steps.skill_setup.outcome == 'success' && steps.skill.outcome == 'success' + env: + BODY_FILE: ${{ steps.skill.outputs.response_file }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/post-response.js + + # --- Route: implementation-like routes (approval request) --- + approval: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + needs.portal.outputs.needs_approval == 'true' + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Prepare approval request + id: approval + env: + INPUT_MENTION: ${{ inputs.agent_handle }} + ISSUE_BODY: ${{ needs.portal.outputs.issue_body }} + ISSUE_TITLE: ${{ needs.portal.outputs.issue_title }} + REQUEST_TEXT: ${{ needs.portal.outputs.body }} + ROUTE: ${{ needs.portal.outputs.route }} + SOURCE_KIND: ${{ needs.portal.outputs.source_kind }} + SUMMARY: ${{ needs.portal.outputs.summary }} + TARGET_KIND: ${{ needs.portal.outputs.target_kind }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + TARGET_URL: ${{ needs.portal.outputs.target_url }} + WORKFLOW_FILE: agent-implement.yml + run: node .agent/dist/cli/prepare-approval.js + + - name: Post approval request + env: + BODY_FILE: ${{ steps.approval.outputs.body_file }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: ${{ needs.portal.outputs.target_kind == 'discussion' && 'discussion_comment' || 'issue_comment' }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/post-response.js + + # --- Route: implementation-like routes (explicit, no approval gate) --- + # Runs only when the user explicitly requested the route or applied the + # matching label. Triaged implementation-like decisions still go through the + # approval job above. + implement: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + (needs.portal.outputs.route == 'implement' || needs.portal.outputs.route == 'create-action') && + needs.portal.outputs.needs_approval == 'false' + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Create implementation issue + if: needs.portal.outputs.target_kind != 'issue' + id: create_issue + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + ISSUE_BODY: ${{ needs.portal.outputs.issue_body }} + ISSUE_TITLE: ${{ needs.portal.outputs.issue_title }} + SOURCE_KIND: ${{ needs.portal.outputs.source_kind }} + TARGET_URL: ${{ needs.portal.outputs.target_url }} + run: node .agent/dist/cli/create-issue.js + + - name: Dispatch agent-implement + env: + # APPROVAL_COMMENT_URL is intentionally empty on the explicit path — + # no approval comment exists, and downstream status comments would + # otherwise render "Approval: <url>" misleadingly. + APPROVAL_COMMENT_URL: "" + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ISSUE_NUMBER: ${{ steps.create_issue.outputs.issue_number || needs.portal.outputs.target_number }} + IMPLEMENTATION_ROUTE: ${{ needs.portal.outputs.route }} + REQUESTED_BY: ${{ needs.portal.outputs.requested_by }} + REQUEST_TEXT: ${{ needs.portal.outputs.body }} + SESSION_FORK_FROM_THREAD_KEY: ${{ github.repository }}:${{ needs.portal.outputs.target_kind }}:${{ needs.portal.outputs.target_number }}:answer:default + BASE_PR: ${{ needs.portal.outputs.base_pr }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + run: node .agent/dist/cli/dispatch-agent-implement.js + + - name: Prepare link-back body + if: needs.portal.outputs.target_kind != 'issue' + id: linkback_body + env: + BODY_FILE: ${{ runner.temp }}/implement-linkback.md + ISSUE_URL: ${{ steps.create_issue.outputs.issue_url }} + run: | + set -euo pipefail + # No workflow-run link: agent-implement.yml is dispatched + # fire-and-forget, so its run URL isn't known here. The tracking + # issue is where the final status comment lands. + printf '%s\n' \ + "Implementing this request — tracking in ${ISSUE_URL}." \ + > "${BODY_FILE}" + echo "body_file=${BODY_FILE}" >> "$GITHUB_OUTPUT" + + - name: Post link-back to original surface + if: needs.portal.outputs.target_kind != 'issue' + env: + BODY_FILE: ${{ steps.linkback_body.outputs.body_file }} + DISCUSSION_ID: ${{ needs.portal.outputs.discussion_node_id }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REPLY_TO_ID: ${{ needs.portal.outputs.reply_to_id }} + RESPONSE_KIND: ${{ needs.portal.outputs.response_kind }} + REVIEW_COMMENT_ID: ${{ needs.portal.outputs.review_comment_id }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/post-response.js + + - name: React with thumbs up + if: github.event.action != 'edited' + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + REACTION_SUBJECT_ID: ${{ needs.portal.outputs.reaction_subject_id }} + REACTION_CONTENT: THUMBS_UP + run: node .agent/dist/cli/add-reaction.js + + # --- Route: orchestrate --- + orchestrate: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + needs.portal.outputs.route == 'orchestrate' && + (needs.portal.outputs.target_kind == 'issue' || needs.portal.outputs.target_kind == 'pull_request') + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + id: runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Dispatch orchestrator + env: + AUTOMATION_CURRENT_ROUND: "1" + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + REQUESTED_BY: ${{ needs.portal.outputs.requested_by }} + REQUEST_TEXT: ${{ needs.portal.outputs.body }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: orchestrate + SOURCE_CONCLUSION: requested + AUTHOR_ASSOCIATION: ${{ needs.portal.outputs.association }} + ACCESS_POLICY: ${{ inputs.access_policy }} + REPOSITORY_PRIVATE: ${{ github.event.repository.private && 'true' || 'false' }} + TARGET_KIND: ${{ needs.portal.outputs.target_kind }} + TARGET_NUMBER: ${{ needs.portal.outputs.target_number }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js + + # --- Route: review (dual-agent) --- + review: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + needs.portal.outputs.route == 'review' && + needs.portal.outputs.target_kind == 'pull_request' && + github.event.action != 'edited' + uses: ./.github/workflows/agent-review.yml + with: + pr_number: ${{ needs.portal.outputs.target_number }} + requested_by: ${{ needs.portal.outputs.requested_by }} + request_text: ${{ needs.portal.outputs.body }} + runs_on: ${{ inputs.runs_on }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + automation_mode: ${{ inputs.automation_mode }} + automation_max_rounds: ${{ inputs.automation_max_rounds }} + secrets: inherit + + # --- Route: fix-pr --- + fix-pr: + needs: portal + if: >- + needs.portal.outputs.should_respond == 'true' && + needs.portal.outputs.route == 'fix-pr' && + needs.portal.outputs.target_kind == 'pull_request' && + github.event.action != 'edited' + uses: ./.github/workflows/agent-fix-pr.yml + with: + runs_on: ${{ inputs.runs_on }} + pr_number: ${{ needs.portal.outputs.target_number }} + requested_by: ${{ needs.portal.outputs.requested_by }} + request_text: ${{ needs.portal.outputs.body }} + request_comment_id: ${{ needs.portal.outputs.source_comment_id }} + request_comment_url: ${{ needs.portal.outputs.source_comment_url }} + request_source_kind: ${{ needs.portal.outputs.source_kind }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + automation_mode: ${{ inputs.automation_mode }} + automation_max_rounds: ${{ inputs.automation_max_rounds }} + secrets: inherit diff --git a/.github/workflows/agent-rubrics-initialization.yml b/.github/workflows/agent-rubrics-initialization.yml new file mode 100644 index 0000000..b0ed82a --- /dev/null +++ b/.github/workflows/agent-rubrics-initialization.yml @@ -0,0 +1,117 @@ +name: Agent / Rubrics / Initialization + +on: + workflow_dispatch: + inputs: + rubrics_ref: + description: "Rubrics branch to create on first run" + required: false + default: agent/rubrics + initialization_context: + description: "Optional context, links, PRs, issues, or preferences for initial rubric seeding" + required: false + default: "" + +permissions: + contents: write + discussions: read + issues: read + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-rubrics-${{ github.repository }}-initialization + cancel-in-progress: false + +jobs: + initialize: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + RUBRICS_REF: ${{ inputs.rubrics_ref || vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve rubrics initialization provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: rubrics-initialization + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Reject existing rubrics branch + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + run: | + set -euo pipefail + refs_file="$(mktemp)" + trap 'rm -f "$refs_file"' EXIT + gh api "repos/${GITHUB_REPOSITORY}/git/matching-refs/heads/${RUBRICS_REF}" --jq '.[].ref' >"$refs_file" + exact_ref="refs/heads/${RUBRICS_REF}" + if grep -Fxq "$exact_ref" "$refs_file"; then + echo "Rubrics branch ${GITHUB_REPOSITORY}@${RUBRICS_REF} already exists. Initialization is first-run only; use Agent / Rubrics / Update for later rubric learning." >&2 + exit 1 + fi + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: rubrics-initialization + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Initialize and seed rubrics + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: rubrics-initialization + route: rubrics-initialization + lane: initialization + memory_mode_override: 'read-only' + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_mode_override: 'enabled' + rubrics_ref: ${{ env.RUBRICS_REF }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: none + request_text: | + Initialize user/team rubrics for this repository. + + Supplied initialization context: + ${{ inputs.initialization_context }} + requested_by: ${{ github.repository_owner }} + source_kind: workflow_dispatch + target_kind: repository + target_number: '0' + target_url: ${{ github.server_url }}/${{ github.repository }} + reasoning_effort: high + workflow: agent-rubrics-initialization.yml diff --git a/.github/workflows/agent-rubrics-review.yml b/.github/workflows/agent-rubrics-review.yml new file mode 100644 index 0000000..ad93301 --- /dev/null +++ b/.github/workflows/agent-rubrics-review.yml @@ -0,0 +1,168 @@ +name: Agent / Rubrics / Review + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to review against rubrics" + required: true + requested_by: + description: "GitHub login that requested the run" + required: false + request_text: + description: "Original user request text forwarded from the portal" + required: false + rubrics_ref: + description: "Rubrics branch to read" + required: false + default: agent/rubrics + rubrics_limit: + description: "Maximum selected rubrics to score" + required: false + default: "" + post_comment: + description: "Post the rubric review as a PR comment" + required: false + default: "true" + session_bundle_mode: + description: "Session bundle persistence mode (defaults to repository variable AGENT_SESSION_BUNDLE_MODE or 'auto')" + required: false + default: "" + workflow_call: + inputs: + pr_number: + type: string + required: true + requested_by: + type: string + required: false + request_text: + type: string + required: false + runs_on: + type: string + default: "" + rubrics_ref: + type: string + default: agent/rubrics + rubrics_limit: + type: string + default: "" + post_comment: + type: string + default: "false" + session_bundle_mode: + type: string + default: "" + +permissions: + actions: read + contents: read + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +jobs: + rubrics-review: + runs-on: ${{ fromJson(inputs.runs_on || vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve rubrics review provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: rubrics-review + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: rubrics-review + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run rubrics review + id: review + continue-on-error: true + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: rubrics-review + route: rubrics-review + lane: rubrics-review + memory_mode_override: 'read-only' + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ inputs.rubrics_ref || vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ inputs.rubrics_limit || vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: none + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + source_kind: workflow_dispatch + target_kind: pull_request + target_number: ${{ inputs.pr_number }} + target_url: ${{ github.server_url }}/${{ github.repository }}/pull/${{ inputs.pr_number }} + reasoning_effort: high + workflow: agent-rubrics-review.yml + + - name: Persist rubrics review artifact + if: ${{ steps.review.outputs.response_file != '' }} + run: | + set -euo pipefail + cp "${{ steps.review.outputs.response_file }}" "${{ runner.temp }}/review.md" + if [ -f "${{ steps.review.outputs.session_log_file }}" ]; then + cp "${{ steps.review.outputs.session_log_file }}" "${{ runner.temp }}/events.jsonl" + fi + + - uses: actions/upload-artifact@v4 + if: ${{ steps.review.outputs.response_file != '' }} + with: + name: rubrics-review-${{ inputs.pr_number }} + path: | + ${{ runner.temp }}/review.md + ${{ runner.temp }}/events.jsonl + retention-days: 30 + + - name: Post rubric review comment + if: inputs.post_comment == 'true' && steps.review.outputs.response_file != '' + env: + BODY_FILE: ${{ steps.review.outputs.response_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + AGENT_COLLAPSE_OLD_REVIEWS: ${{ vars.AGENT_COLLAPSE_OLD_REVIEWS }} + RESPONSE_KIND: pr_comment + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/post-response.js + + - name: Report skipped rubric review + if: always() && steps.review.outcome == 'failure' + run: | + echo "::warning title=Rubrics review skipped::Rubrics review failed before producing a response; continuing because rubric scoring is advisory." diff --git a/.github/workflows/agent-rubrics-update.yml b/.github/workflows/agent-rubrics-update.yml new file mode 100644 index 0000000..19b93af --- /dev/null +++ b/.github/workflows/agent-rubrics-update.yml @@ -0,0 +1,134 @@ +name: Agent / Rubrics / Update + +on: + pull_request_target: + types: [closed] + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to learn rubrics from" + required: true + rubrics_ref: + description: "Rubrics branch to update" + required: false + default: agent/rubrics + +permissions: + contents: write + issues: write + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-rubrics-${{ github.repository }}-pr-${{ github.event.pull_request.number || inputs.pr_number || github.run_id }} + cancel-in-progress: false + +jobs: + update: + # Rubrics are learned automatically only from merged PRs that had review + # interaction. Manual dispatch can inspect any PR number explicitly. This + # keeps unmerged/abandoned PR feedback and trivial merges from becoming + # normative user preference without review. + if: >- + github.event_name == 'workflow_dispatch' || + ( + github.event.pull_request.merged == true && + ( + github.event.pull_request.comments > 0 || + github.event.pull_request.review_comments > 0 + ) + ) + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + env: + PR_NUMBER: ${{ inputs.pr_number || github.event.pull_request.number }} + PR_URL: ${{ github.event.pull_request.html_url || format('{0}/{1}/pull/{2}', github.server_url, github.repository, inputs.pr_number) }} + RUBRICS_REF: ${{ inputs.rubrics_ref || vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve rubrics update provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: rubrics-update + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: rubrics-update + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Update user rubrics from PR history + id: rubrics_update + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + prompt: rubrics-update + route: rubrics-update + lane: update + memory_mode_override: 'read-only' + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_mode_override: 'enabled' + rubrics_ref: ${{ env.RUBRICS_REF }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_policy: none + request_text: >- + Learn durable user/team rubrics from this PR conversation if warranted. Skip one-off feedback and duplicate existing rubrics. + requested_by: ${{ github.actor }} + source_kind: pull_request + target_kind: pull_request + target_number: ${{ env.PR_NUMBER }} + target_url: ${{ env.PR_URL }} + reasoning_effort: medium + workflow: agent-rubrics-update.yml + + - name: Prepare rubrics update summary + if: always() && steps.rubrics_update.outputs.response_file != '' + id: rubrics_summary + env: + RESPONSE_FILE: ${{ steps.rubrics_update.outputs.response_file }} + RUBRICS_COMMITTED: ${{ steps.rubrics_update.outputs.rubrics_committed }} + RUBRICS_REF: ${{ env.RUBRICS_REF }} + RUBRICS_STEP_OUTCOME: ${{ steps.rubrics_update.outcome }} + run: node .agent/dist/cli/prepare-rubrics-update-summary.js + + - name: Post rubrics update summary + if: always() && steps.rubrics_summary.outputs.body_file != '' + env: + BODY_FILE: ${{ steps.rubrics_summary.outputs.body_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: issue_comment + TARGET_NUMBER: ${{ env.PR_NUMBER }} + run: node .agent/dist/cli/post-response.js diff --git a/.github/workflows/agent-self-approve.yml b/.github/workflows/agent-self-approve.yml new file mode 100644 index 0000000..348dee7 --- /dev/null +++ b/.github/workflows/agent-self-approve.yml @@ -0,0 +1,230 @@ +name: Agent / Self Approve + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to self-approve" + required: true + requested_by: + description: "GitHub login that requested the run" + required: false + request_text: + description: "Original request text" + required: false + source_conclusion: + description: "Optional source review verdict from the orchestrator handoff" + required: false + default: "" + source_recommended_next_step: + description: "Optional source review recommended next step from the orchestrator handoff" + required: false + default: "" + session_bundle_mode: + description: "Session bundle persistence mode" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + orchestration_enabled: + description: "Whether this run belongs to an explicit orchestrator chain" + required: false + default: "false" + +permissions: + actions: read + contents: read + pull-requests: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-self-approve-${{ github.repository }}-${{ inputs.pr_number }} + cancel-in-progress: false + +jobs: + self-approve: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + persist-credentials: false + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Prepare self-approval + id: prepare + env: + AGENT_ALLOW_SELF_APPROVE: ${{ vars.AGENT_ALLOW_SELF_APPROVE || 'false' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + SOURCE_RECOMMENDED_NEXT_STEP: ${{ inputs.source_recommended_next_step }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/prepare-self-approve.js + + - name: Post self-approval stop + if: >- + always() && + steps.prepare.outcome == 'success' && + steps.prepare.outputs.should_run != 'true' && + steps.prepare.outputs.body_file != '' + env: + BODY_FILE: ${{ steps.prepare.outputs.body_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: pr_comment + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/post-response.js + + - name: Resolve self-approval provider + id: provider + if: steps.prepare.outputs.should_run == 'true' + uses: ./.github/actions/resolve-agent-provider + with: + route: agent-self-approve + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Install self-approval provider + if: steps.prepare.outputs.should_run == 'true' + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve task timeout + if: steps.prepare.outputs.should_run == 'true' + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: agent-self-approve + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run self-approval agent + id: agent + if: steps.prepare.outputs.should_run == 'true' + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ github.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-reads + prompt: agent-self-approve + route: agent-self-approve + lane: self-approve + memory_mode_override: read-only + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_mode_override: read-only + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_bundle_mode: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + session_policy: track-only + request_text: ${{ inputs.request_text }} + requested_by: ${{ inputs.requested_by || github.actor }} + source_kind: workflow_dispatch + target_kind: pull_request + target_number: ${{ inputs.pr_number }} + target_url: ${{ github.server_url }}/${{ github.repository }}/pull/${{ inputs.pr_number }} + reasoning_effort: xhigh + workflow: agent-self-approve.yml + env: + SELF_APPROVE_EXPECTED_HEAD_SHA: ${{ steps.prepare.outputs.head_sha }} + SELF_APPROVE_SOURCE_CONCLUSION: ${{ inputs.source_conclusion }} + SELF_APPROVE_SOURCE_RECOMMENDED_NEXT_STEP: ${{ inputs.source_recommended_next_step }} + + - name: Resolve self-approval result + id: result + if: >- + always() && + steps.prepare.outputs.should_run == 'true' + env: + AGENT_ALLOW_SELF_APPROVE: ${{ vars.AGENT_ALLOW_SELF_APPROVE || 'false' }} + EXPECTED_HEAD_SHA: ${{ steps.prepare.outputs.head_sha }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_RUN_ID: ${{ github.run_id }} + GITHUB_SERVER_URL: ${{ github.server_url }} + RESPONSE_FILE: ${{ steps.agent.outputs.response_file }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/resolve-self-approve.js + + - name: Post self-approval status + if: >- + always() && + steps.prepare.outputs.should_run == 'true' && + (steps.result.outcome == 'failure' || steps.result.outputs.approved != 'true') + env: + BODY_FILE: ${{ steps.result.outputs.body_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: pr_comment + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/post-response.js + + - uses: actions/upload-artifact@v4 + if: >- + always() && + steps.prepare.outputs.should_run == 'true' + with: + name: agent-self-approve-result-${{ inputs.pr_number }} + path: | + ${{ steps.agent.outputs.response_file }} + ${{ steps.agent.outputs.session_log_file }} + ${{ steps.agent.outputs.raw_stdout_file }} + ${{ steps.agent.outputs.raw_stderr_file }} + ${{ steps.result.outputs.body_file }} + if-no-files-found: ignore + retention-days: 30 + + - name: Orchestrate automation handoff + if: >- + always() && + steps.prepare.outputs.should_run == 'true' && + steps.result.outcome == 'success' && + inputs.orchestration_enabled == 'true' + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ORCHESTRATION_ENABLED: ${{ inputs.orchestration_enabled }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: agent-self-approve + SOURCE_CONCLUSION: ${{ steps.result.outputs.conclusion }} + SOURCE_HANDOFF_CONTEXT: ${{ steps.result.outputs.handoff_context }} + SOURCE_RUN_ID: ${{ github.run_id }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js diff --git a/.github/workflows/agent-self-merge.yml b/.github/workflows/agent-self-merge.yml new file mode 100644 index 0000000..30e884f --- /dev/null +++ b/.github/workflows/agent-self-merge.yml @@ -0,0 +1,128 @@ +name: Agent / Self Merge + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number to self-merge" + required: true + requested_by: + description: "GitHub login that requested the run" + required: false + request_text: + description: "Original request text" + required: false + session_bundle_mode: + description: "Session bundle persistence mode" + required: false + default: "" + automation_mode: + description: "Post-action orchestration mode (disabled, heuristics, agent)" + required: false + default: "disabled" + automation_current_round: + description: "Current automation handoff round" + required: false + default: "1" + automation_max_rounds: + description: "Maximum automation handoff rounds" + required: false + default: "12" + orchestration_enabled: + description: "Whether this run belongs to an explicit orchestrator chain" + required: false + default: "false" + +permissions: + actions: read + checks: read + contents: write + issues: write + pull-requests: write + statuses: read + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-self-merge-${{ github.repository }}-${{ inputs.pr_number }} + cancel-in-progress: false + +jobs: + self-merge: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + persist-credentials: false + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + + - name: Resolve self-merge + id: result + env: + AGENT_ALLOW_SELF_MERGE: ${{ vars.AGENT_ALLOW_SELF_MERGE || 'false' }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + GITHUB_RUN_ID: ${{ github.run_id }} + GITHUB_SERVER_URL: ${{ github.server_url }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/resolve-self-merge.js + + - name: Post self-merge status + if: >- + always() && + steps.result.outcome == 'success' && + steps.result.outputs.status_post == 'true' && + steps.result.outputs.body_file != '' + env: + BODY_FILE: ${{ steps.result.outputs.body_file }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + RESPONSE_KIND: pr_comment + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/post-response.js + + - uses: actions/upload-artifact@v4 + if: >- + always() && + steps.result.outputs.body_file != '' + with: + name: agent-self-merge-result-${{ inputs.pr_number }} + path: ${{ steps.result.outputs.body_file }} + if-no-files-found: ignore + retention-days: 30 + + - name: Orchestrate automation handoff + if: >- + always() && + steps.result.outcome == 'success' && + inputs.orchestration_enabled == 'true' + env: + AUTOMATION_CURRENT_ROUND: ${{ inputs.automation_current_round }} + AUTOMATION_MAX_ROUNDS: ${{ inputs.automation_max_rounds }} + AUTOMATION_MODE: ${{ inputs.automation_mode }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + GH_TOKEN: ${{ steps.auth.outputs.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + ORCHESTRATION_ENABLED: ${{ inputs.orchestration_enabled }} + REQUESTED_BY: ${{ inputs.requested_by || github.actor }} + REQUEST_TEXT: ${{ inputs.request_text }} + SESSION_BUNDLE_MODE: ${{ inputs.session_bundle_mode || vars.AGENT_SESSION_BUNDLE_MODE || 'auto' }} + SOURCE_ACTION: agent-self-merge + SOURCE_CONCLUSION: ${{ steps.result.outputs.conclusion }} + SOURCE_RUN_ID: ${{ github.run_id }} + TARGET_KIND: pull_request + TARGET_NUMBER: ${{ inputs.pr_number }} + run: node .agent/dist/cli/dispatch-agent-orchestrator.js diff --git a/.github/workflows/agent-update.yml b/.github/workflows/agent-update.yml new file mode 100644 index 0000000..f10e28e --- /dev/null +++ b/.github/workflows/agent-update.yml @@ -0,0 +1,287 @@ +name: Agent / Update + +on: + schedule: + # GitHub cron has no native every-14-days interval; run near-biweekly on + # the 1st and 15th of each month. + - cron: "17 9 1,15 * *" + workflow_dispatch: + inputs: + source_repo: + description: "Source Sepo agent repository to update from" + required: false + default: "self-evolving/repo" + source_ref: + description: "Optional source Sepo agent ref; defaults to latest stable release tag" + required: false + default: "" + update_skills: + description: "Also update .skills directories" + required: false + type: boolean + default: false + update_agent_md: + description: "Also update AGENT.md when it is agent-owned" + required: false + type: boolean + default: false + force: + description: "Ignore an open Sepo update PR and start from the default branch" + required: false + type: boolean + default: false + +permissions: + actions: write + contents: write + issues: write + pull-requests: write + id-token: write # required for GitHub Actions OIDC broker exchange + +concurrency: + group: agent-update-${{ github.repository }} + cancel-in-progress: false + +env: + UPDATE_SOURCE_REPO: ${{ inputs.source_repo || 'self-evolving/repo' }} + UPDATE_SOURCE_REF: ${{ inputs.source_ref || '' }} + DEFAULT_UPDATE_SOURCE_REF: main + UPDATE_SKILLS: ${{ inputs.update_skills && 'true' || 'false' }} + UPDATE_AGENT_MD: ${{ inputs.update_agent_md && 'true' || 'false' }} + UPDATE_BRANCH_PREFIX: agent/update-agent-infra- + +jobs: + gate: + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + outputs: + skip: ${{ steps.result.outputs.skip }} + reason: ${{ steps.result.outputs.reason }} + existing_pr_url: ${{ steps.pending.outputs.pr_url }} + existing_pr_number: ${{ steps.pending.outputs.pr_number }} + existing_pr_branch: ${{ steps.pending.outputs.branch }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 1 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + token: ${{ github.token }} + + - name: Resolve scheduled activity gate + id: schedule + uses: ./.github/actions/scheduled-activity-gate + with: + github_token: ${{ github.token }} + schedule_policy: ${{ vars.AGENT_AUTO_UPDATE == 'false' && '{"workflow_overrides":{"agent-update.yml":"disabled"}}' || vars.AGENT_SCHEDULE_POLICY || '' }} + workflow: agent-update.yml + + - name: Check pending update PR + id: pending + if: steps.schedule.outputs.skip != 'true' + env: + GH_TOKEN: ${{ github.token }} + GITHUB_REPOSITORY: ${{ github.repository }} + IGNORE_EXISTING_UPDATE_PR: ${{ inputs.force && 'true' || 'false' }} + UPDATE_BRANCH_PREFIX: ${{ env.UPDATE_BRANCH_PREFIX }} + run: bash .agent/scripts/resolve-pending-update-pr.sh + + - name: Resolve gate result + id: result + env: + SCHEDULE_REASON: ${{ steps.schedule.outputs.reason }} + SCHEDULE_SKIP: ${{ steps.schedule.outputs.skip }} + run: | + set -euo pipefail + write_output() { + local name="$1" + local value="$2" + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" + } + + if [ "${SCHEDULE_SKIP}" = "true" ]; then + write_output "skip" "true" + write_output "reason" "${SCHEDULE_REASON}" + else + write_output "skip" "false" + write_output "reason" "${SCHEDULE_REASON}" + fi + + - name: Write skipped summary + if: steps.result.outputs.skip == 'true' + env: + EXISTING_PR_URL: ${{ steps.pending.outputs.pr_url }} + REASON: ${{ steps.result.outputs.reason }} + run: | + set -euo pipefail + if [ -n "${EXISTING_PR_URL}" ]; then + printf '%s\n' "Skipped Sepo update check: ${REASON} (${EXISTING_PR_URL})." >> "$GITHUB_STEP_SUMMARY" + else + printf '%s\n' "Skipped Sepo update check: ${REASON}." >> "$GITHUB_STEP_SUMMARY" + fi + + update: + needs: gate + if: needs.gate.outputs.skip != 'true' + runs-on: ${{ fromJson(vars.AGENT_RUNS_ON || '["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + fetch-depth: 0 + persist-credentials: false + token: ${{ github.token }} + + - name: Resolve update target checkout + id: update_target + env: + EXISTING_PR_BRANCH: ${{ needs.gate.outputs.existing_pr_branch }} + GITHUB_TOKEN: ${{ github.token }} + TARGET_WORKTREE: ${{ runner.temp }}/agent-update-target + run: | + set -euo pipefail + write_output() { + local name="$1" + local value="$2" + local delim="DELIM_${RANDOM}_${RANDOM}_$$" + { + printf '%s<<%s\n' "$name" "$delim" + printf '%s\n' "$value" + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" + } + + if [ -n "${EXISTING_PR_BRANCH}" ]; then + auth_header="$(printf 'x-access-token:%s' "${GITHUB_TOKEN}" | base64 | tr -d '\n')" + git -c "http.https://github.com/.extraheader=AUTHORIZATION: basic ${auth_header}" \ + fetch --no-tags origin "refs/heads/${EXISTING_PR_BRANCH}:refs/remotes/origin/${EXISTING_PR_BRANCH}" + git worktree add -B "${EXISTING_PR_BRANCH}" "${TARGET_WORKTREE}" "origin/${EXISTING_PR_BRANCH}" + write_output "path" "${TARGET_WORKTREE}" + write_output "mode" "existing-pr-worktree" + else + write_output "path" "${GITHUB_WORKSPACE}" + write_output "mode" "runtime-checkout" + fi + + - name: Resolve GitHub auth + id: auth + uses: ./.github/actions/resolve-github-auth + with: + app_id: ${{ secrets.AGENT_APP_ID }} + app_private_key: ${{ secrets.AGENT_APP_PRIVATE_KEY }} + pat: ${{ secrets.AGENT_PAT }} + fallback_token: ${{ github.token }} + + - name: Resolve update provider + id: provider + uses: ./.github/actions/resolve-agent-provider + with: + route: skill + default_provider: ${{ vars.AGENT_DEFAULT_PROVIDER || 'auto' }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Setup agent runtime + uses: ./.github/actions/setup-agent-runtime + with: + install_codex: ${{ steps.provider.outputs.install_codex }} + install_claude: ${{ steps.provider.outputs.install_claude }} + + - name: Resolve update source + id: update_source + env: + GH_TOKEN: ${{ steps.auth.outputs.token }} + UPDATE_SOURCE_REPO: ${{ env.UPDATE_SOURCE_REPO }} + UPDATE_SOURCE_REF: ${{ env.UPDATE_SOURCE_REF }} + DEFAULT_UPDATE_SOURCE_REF: ${{ env.DEFAULT_UPDATE_SOURCE_REF }} + run: bash .agent/scripts/resolve-update-source.sh + + - name: Write update source summary + env: + SOURCE_KIND: ${{ steps.update_source.outputs.source_kind }} + SOURCE_REASON: ${{ steps.update_source.outputs.reason }} + SOURCE_REF: ${{ steps.update_source.outputs.source_ref }} + SOURCE_REPO: ${{ steps.update_source.outputs.source_repo }} + SOURCE_SHA: ${{ steps.update_source.outputs.source_sha }} + run: | + set -euo pipefail + printf '%s\n' "Sepo update source: ${SOURCE_REPO}@${SOURCE_REF} (${SOURCE_SHA}; ${SOURCE_KIND})." >> "$GITHUB_STEP_SUMMARY" + if [ -n "${SOURCE_REASON}" ]; then + printf '%s\n' "${SOURCE_REASON}." >> "$GITHUB_STEP_SUMMARY" + fi + + - name: Resolve task timeout + id: task_timeout + env: + AGENT_TASK_TIMEOUT_POLICY: ${{ vars.AGENT_TASK_TIMEOUT_POLICY || '' }} + ROUTE: skill + run: node .agent/dist/cli/resolve-task-timeout.js + + - name: Run update agent + id: agent + timeout-minutes: ${{ fromJson(steps.task_timeout.outputs.minutes || '30') }} + uses: ./.github/actions/run-agent-task + with: + agent: ${{ steps.provider.outputs.provider }} + github_token: ${{ steps.auth.outputs.token }} + openai_api_key: ${{ secrets.OPENAI_API_KEY }} + claude_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + permission_mode: approve-all + skill: update-agent + route: skill + lane: scheduled-update + memory_mode_override: read-only + memory_ref: ${{ vars.AGENT_MEMORY_REF || 'agent/memory' }} + memory_policy: ${{ vars.AGENT_MEMORY_POLICY || '' }} + rubrics_ref: ${{ vars.AGENT_RUBRICS_REF || 'agent/rubrics' }} + rubrics_policy: ${{ vars.AGENT_RUBRICS_POLICY || '' }} + rubrics_limit: ${{ vars.AGENT_RUBRICS_LIMIT || '10' }} + session_policy: track-only + request_text: | + Run a Sepo agent infrastructure update check for this repository. + + Confirmed inputs: + - target repository: ${{ github.repository }} + - target default branch: ${{ github.event.repository.default_branch }} + - runtime checkout path: ${{ github.workspace }} + - update target path: ${{ steps.update_target.outputs.path }} + - update target mode: ${{ steps.update_target.outputs.mode }} + - source agent repo/ref: ${{ steps.update_source.outputs.source_repo }}@${{ steps.update_source.outputs.source_ref }} + - source agent SHA: ${{ steps.update_source.outputs.source_sha }} + - source resolution: ${{ steps.update_source.outputs.source_kind }} + - existing update PR number: ${{ needs.gate.outputs.existing_pr_number || 'none' }} + - existing update PR branch: ${{ needs.gate.outputs.existing_pr_branch || 'none' }} + - update branch: use `${{ env.UPDATE_BRANCH_PREFIX }}<yyyymmdd>` + - update .skills directories: ${{ env.UPDATE_SKILLS }} + - update AGENT.md when agent-owned: ${{ env.UPDATE_AGENT_MD }} + - remove obsolete or legacy files: false + - post-merge workflows: document only + + Runtime actions and scripts are loaded from the default-branch checkout + at the runtime checkout path. If an existing update PR number and branch + are not `none`, update that branch and PR in the update target path + instead of opening a new PR; do not check out the existing PR branch in + the runtime checkout path. Otherwise, open a pull request only when the + update produces changes. If the target is already current, leave no PR + and report that no update was needed. + When a PR is opened, title and summarize it as: + `Update Sepo from <installed version/ref> to ${{ steps.update_source.outputs.source_ref }}/${{ steps.update_source.outputs.source_sha }}`. + requested_by: ${{ github.actor }} + source_kind: workflow_dispatch + target_kind: repository + target_number: "0" + target_url: ${{ github.server_url }}/${{ github.repository }} + workflow: agent-update.yml + + - name: Write update summary + if: always() && steps.agent.outputs.response_file != '' + env: + BODY_FILE: ${{ steps.agent.outputs.response_file }} + run: | + if [ -f "$BODY_FILE" ]; then + cat "$BODY_FILE" >> "$GITHUB_STEP_SUMMARY" + fi diff --git a/.github/workflows/test-scripts.yml b/.github/workflows/test-scripts.yml new file mode 100644 index 0000000..6361196 --- /dev/null +++ b/.github/workflows/test-scripts.yml @@ -0,0 +1,77 @@ +name: Test Scripts + +on: + pull_request: + workflow_dispatch: + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install and build + run: | + set -euo pipefail + cd .agent + npm ci + npm run build + + - name: Run tests + run: | + set -euo pipefail + cd .agent + npm test + + - name: Parse workflow and action YAML + run: | + set -euo pipefail + ruby -e 'require "yaml"; (Dir[".github/workflows/*.yml"] + Dir[".github/actions/*/action.yml"] + Dir[".agent/action-templates/*.yml"]).sort.each { |file| YAML.load_file(file) }' + + - name: Validate gh-authenticated workflow steps + run: | + set -euo pipefail + ruby <<'RUBY' + require "yaml" + + failures = [] + + Dir[".github/workflows/*.yml"].sort.each do |file| + workflow = YAML.load_file(file) + jobs = workflow.fetch("jobs", {}) + + jobs.each_value do |job| + Array(job["steps"]).each do |step| + next unless step.is_a?(Hash) + + allowed_tools = step.dig("with", "allowed_tools").to_s + next unless allowed_tools.include?("Bash(gh *)") + + env = step["env"] || {} + next if env.key?("GH_TOKEN") + + step_name = step["name"] || "(unnamed step)" + failures << "#{file}: #{step_name} allows gh without GH_TOKEN" + end + end + end + + abort(failures.join("\n")) unless failures.empty? + RUBY + + - name: Shell syntax checks + run: | + set -euo pipefail + bash -n .agent/scripts/post-agent-verify.sh + bash -n .agent/scripts/resolve-scheduled-activity-gate.sh + bash -n .agent/scripts/resolve-pending-update-pr.sh + bash -n .agent/scripts/resolve-update-source.sh + bash -n .agent/scripts/resolve-discussion-post-gate.sh + bash -n .github/actions/check-agent-action-expiration/check-expiration.sh + + - name: Diff hygiene + run: git diff --check diff --git a/.gitignore b/.gitignore index 1810b39..7a55528 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ app/build/ buildSrc/build/ oa-chat/node_modules/ oa-chat/dist/ +.agent/dist/ +.agent/node_modules/