Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* App pull-request / merge-request routes.
*
* GET /:id/pull-requests → open forge requests
* POST /:id/pull-requests/:number/resolve → queue a review-loop agent
* POST /:id/pull-requests/:number/review → queue pr-reviewer for ONE PR
* POST /:id/pull-requests/:number/do-review → queue /do:review for ONE PR
* POST /:id/pull-requests/:number/merge → merge it now, no agent
*
* Three of the four queue an agent. `/resolve` queues PortOS's existing
* review-loop follow-up, which owns fetching feedback, fixing the branch,
* waiting for checks, and merging — and starts it immediately, because pressing
* the button is the approval. `/review` queues the `pr-reviewer` scheduled task
* narrowed to a single request, so the security-scan → review pipeline that
* normally sweeps every external PR can be pointed at one. `/do-review` runs the
* bundled `/do:review` workflow against one request with the install's Code
* Review Defaults and publishes an inline review — the only one of the three
* that offers a review on EVERY open GitHub PR, whoever opened it, because
* `pr-reviewer` covers untrusted contributors alone. `/merge` is the one that
* queues nothing and spends nothing: the forge's own merge button, for a change
* the user has already read.
*
* That split is why the two agent routes PortOS composes itself (`/resolve`,
* `/do-review`) take `pullRequestRunSettingsSchema` — the provider pin PLUS this
* run's review settings — while `/review` takes the provider pin alone: its run
* is a `pr-reviewer` task whose reviewers come from that scheduled task's own
* stages, so a review setting sent there would be one the server accepts and
* nothing applies.
*/
import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../../lib/errorHandler.js';
import { pullRequestProviderOverrideSchema, pullRequestRunSettingsSchema, reviewerConfigMetadata } from '../../lib/cosValidation.js';
import { claimSafeReviewers, normalizeReviewers, validateRequest } from '../../lib/validation.js';
import { PR_COMPLETIONS, isSelfReviewMode } from '../../lib/prDisposition.js';
import { isTruthyMeta } from '../../services/agentState.js';
import { resolveReviewLoopOptions } from '../../services/codeReview.js';
import { spawnReviewLoopFollowUp } from '../../services/agentWorktreeCleanup.js';
import { listAppPullRequests } from '../../services/appPullRequests.js';
import {
MERGE_METHODS,
DEFAULT_MERGE_METHOD,
isDirectlyMergeablePullRequest,
mergeAppPullRequest,
} from '../../services/appPullRequestMerge.js';
import { forgeScopeMissingError } from '../../services/forgeScopeRefresh.js';
import { isDoReviewTask, spawnPrDoReviewTask } from '../../services/prDoReviewTask.js';
import {
isReviewablePullRequest,
resolvePrReviewerTargetScope,
} from '../../services/prReviewerSecurity.js';
import {
ACTIVE_TASK_STATUSES,
queueTargetedPrReview,
readActiveTasks,
readPendingOnDemandRequests,
reviewActionFor,
} from '../../services/prReviewerTargetedRun.js';
import { loadApp } from './shared.js';
const router = Router();
const pullRequestParamsSchema = z.object({
number: z.coerce.number().int().positive(),
});
// The direct merge's only inputs; the tab always sends both. A caller that omits
// `deleteBranch` gets the conservative answer — the flag is irreversible on the
// forge, and the merge service refuses it outright for a long-lived head.
const pullRequestMergeSchema = z.object({
method: z.enum(MERGE_METHODS).optional(),
deleteBranch: z.boolean().optional(),
});
const isResolveTaskFor = (task, appId, pullRequest) => {
const metadata = task?.metadata;
return ACTIVE_TASK_STATUSES.has(task?.status)
&& isTruthyMeta(metadata?.reviewLoopFollowUp)
&& metadata?.app === appId
&& Number(metadata.reviewLoopPRNumber) === pullRequest.number;
};
// A `/do:review` run pinned to this request. It shares `targetPullRequest` with
// the pr-reviewer match above — one vocabulary for "this task targets PR #N" —
// and `isDoReviewTask` is what tells the two apart.
const isDoReviewTaskFor = (task, appId, pullRequest) => {
const metadata = task?.metadata;
return ACTIVE_TASK_STATUSES.has(task?.status)
&& isDoReviewTask(metadata)
&& metadata?.app === appId
&& Number(metadata.targetPullRequest) === pullRequest.number;
};
// Per-row pr-reviewer eligibility, resolved from the SAME facts the security
// preflight filters on. Without it the tab would paint a Review button on every
// GitHub row, including the ones the route answers with 409 — an action that is
// guaranteed to fail. Only worth the extra `gh repo view` when the forge is
// GitHub; every other forge is ineligible by construction.
async function resolveReviewEligibility(app, result) {
if (result.forge !== 'github') return () => false;
const scope = await resolvePrReviewerTargetScope(app).catch(err => {
console.error(`❌ app-pull-requests: could not resolve pr-reviewer scope: ${err.message}`);
return null;
});
const eligible = new Set();
await Promise.all((result.pullRequests || []).map(async pullRequest => {
if (await isReviewablePullRequest(scope, pullRequest)) eligible.add(pullRequest.number);
}));
return pullRequest => eligible.has(pullRequest.number);
}
// Per-row Do:Review eligibility. Deliberately NOT an authorship test — that is
// the whole point of the action: pr-reviewer covers untrusted contributors only,
// so every other row had no review-only action. What it does gate is what
// slashdo's PR mode actually needs — a GitHub request with a URL to read it by.
// Pure, unlike `resolveReviewEligibility` beside it, so it costs no forge call.
//
// Server-side rather than re-derived in the tab, for the same reason
// `reviewEligible` is: two copies of one rule drift, and the client's copy was
// missing the URL half — painting a button whose only outcome is a 502.
const isDoReviewablePullRequest = (result, pullRequest) =>
result.forge === 'github' && !!pullRequest.url;
// The find-and-project contract shared by the two single-task actions, with the
// matcher passed in. Written once so the "unreadable tasks is not the same as no
// action" rule (`!tasks` → null, never a cheerful empty answer) cannot be
// restated differently per kind.
function actionFor(pullRequest, tasks, appId, matches) {
if (!tasks) return null;
const task = tasks.find(candidate => matches(candidate, appId, pullRequest));
return task ? { taskId: task.id, status: task.status } : null;
}
const taskResponse = task => task ? {
id: task.id,
status: task.status,
description: task.description,
} : null;
async function listWithActionState(app) {
const result = await listAppPullRequests(app);
const pullRequests = Array.isArray(result?.pullRequests) ? result.pullRequests : [];
if (!pullRequests.length || result.transient) return { result, tasks: null };
const [tasks, requests, reviewEligible] = await Promise.all([
readActiveTasks(),
readPendingOnDemandRequests(),
resolveReviewEligibility(app, result),
]);
return {
result: {
...result,
pullRequests: pullRequests.map(pullRequest => ({
...pullRequest,
agentAction: actionFor(pullRequest, tasks, app.id, isResolveTaskFor),
reviewAction: reviewActionFor(pullRequest, tasks, requests, app.id),
doReviewAction: actionFor(pullRequest, tasks, app.id, isDoReviewTaskFor),
reviewEligible: reviewEligible(pullRequest),
doReviewEligible: isDoReviewablePullRequest(result, pullRequest),
mergeEligible: isDirectlyMergeablePullRequest(pullRequest),
})),
},
tasks,
};
}
// The one spelling of "this row is still open", shared by every route that
// re-reads the open set before acting on a single request — the message and
// code would otherwise drift across three doors with nothing catching it.
function findOpenPullRequest(result, number) {
const pullRequest = (result.pullRequests || []).find(candidate => candidate.number === number);
if (!pullRequest) {
throw new ServerError(`Open pull request or merge request #${number} was not found`, {
status: 404,
code: 'PULL_REQUEST_NOT_OPEN',
});
}
return pullRequest;
}
function throwForgeReadError(result) {
if (!result.transient) return;
throw new ServerError(
result.headline || 'Could not read open pull requests',
{
status: 503,
code: 'FORGE_UNAVAILABLE',
context: {
reason: result.reason,
remedy: result.remedy || undefined,
},
},
);
}
// GET /api/apps/:id/pull-requests — list every open PR/MR on the app's forge.
// This intentionally does not gate on the app's Work Tracker: a PLAN.md or
// JIRA app can still have a forge change request that needs attention.
router.get('/:id/pull-requests', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { result } = await listWithActionState(app);
res.json({ appId: app.id, appName: app.name, ...result });
}));
// POST /api/apps/:id/pull-requests/:number/resolve — queue the existing review
// loop against a freshly-read open PR/MR and start it now. Re-reading before
// queueing prevents a closed or replaced request from being attached to an agent
// by stale UI data.
router.post('/:id/pull-requests/:number/resolve', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { number } = validateRequest(pullRequestParamsSchema, req.params);
// Optional provider/model/effort pin from the tab's "Run with" picker — left
// blank, the follow-up resolves the install's active provider exactly as it
// always did — plus this run's review settings (mode, and any reviewer
// override layered over the install's Code Review Defaults).
const runSettings = validateRequest(pullRequestRunSettingsSchema, req.body || {});
const { provider, model, effort } = runSettings;
const selfReview = isSelfReviewMode(runSettings.reviewMode);
const { result, tasks } = await listWithActionState(app);
throwForgeReadError(result);
if (tasks === null && result.pullRequests.length > 0) {
throw new ServerError('Could not inspect existing CoS actions before queueing this request', {
status: 503,
code: 'AGENT_ACTION_UNAVAILABLE',
});
}
const pullRequest = findOpenPullRequest(result, number);
if (!pullRequest.url || !pullRequest.headBranch) {
throw new ServerError(`Pull request or merge request #${number} has no usable forge URL or source branch`, {
status: 502,
code: 'PULL_REQUEST_CONTEXT_UNAVAILABLE',
});
}
const existing = tasks?.find(task => isResolveTaskFor(task, app.id, pullRequest));
if (existing) {
res.json({
appId: app.id,
appName: app.name,
pullRequest,
task: taskResponse(existing),
duplicate: true,
});
return;
}
// Code Review Defaults are the one source for the installed review roster, and
// this run's own reviewer override (when the panel supplied one) layers over
// them with the same task-over-default precedence every other dispatch surface
// uses — `resolveReviewLoopOptions` takes the override in the metadata slot.
// `claimSafeReviewers` removes forge-side Copilot and supplies PortOS's
// unattended coding-review fallback when the defaults contain only Copilot.
//
// Resolved even under self-review, and handed over intact: emptying the roster
// is `spawnReviewLoopFollowUp`'s job, not this route's (see its `selfReview`
// contract), and the stop-mode / applies fields alongside it are not roster
// fields at all.
const reviewOptions = await resolveReviewLoopOptions(reviewerConfigMetadata(runSettings), {
normalize: normalizeReviewers,
isTruthyMeta,
});
const reviewers = claimSafeReviewers(reviewOptions.reviewers, reviewOptions.usernames);
const optionalReviewers = (reviewOptions.optionalReviewers || [])
.filter(reviewer => reviewer !== 'copilot');
const appLabel = String(app.name || app.id).replace(/\s+/g, ' ').trim();
const title = String(pullRequest.title || '(untitled)').replace(/\s+/g, ' ').trim();
const originalTask = {
id: `app-pr-${app.id}-${number}`,
status: 'pending',
priority: 'HIGH',
// Keep forge-controlled text out of the task instructions. The title is
// retained as explicitly delimited data for UI/audit consumers, but the
// autonomous follow-up receives only this static objective.
description: `Resolve and merge ${result.forge === 'gitlab' ? 'MR' : 'PR'} #${number} for ${appLabel}`,
metadata: {
app: app.id,
reviewLoopPRTitle: `--- BEGIN UNTRUSTED FORGE PR TITLE ---\n${title}\n--- END UNTRUSTED FORGE PR TITLE ---`,
// Read by spawnReviewLoopFollowUp below as the source task's pin — the
// same `providerPins` inheritance every other follow-up gets, just seeded
// from this request instead of the original task that opened the PR.
...(provider ? { provider } : {}),
...(model ? { model } : {}),
...(effort ? { effort } : {}),
},
};
const task = await spawnReviewLoopFollowUp({
originalAgentId: null,
originalTask,
prUrl: pullRequest.url,
prBranch: pullRequest.headBranch,
// Null for a same-repo head. A FORK PR's head branch has no
// `origin/<branch>`, so without this the follow-up is queued and then
// blocked at workspace prep — which is every external contribution (#6064).
forkHead: pullRequest.forkHead,
sourceWorkspace: app.repoPath,
prCompletion: PR_COMPLETIONS.REVIEW_THEN_MERGE,
...reviewOptions,
reviewers,
optionalReviewers,
selfReview,
// This button IS the user's approval — start the agent now instead of leaving
// the follow-up as a pending system task the autonomous dequeue only picks up
// while CoS auto-run is in `execute` and under its daily budget (which is why
// it had to be started by hand from the task page).
dispatch: 'immediate',
});
if (!task) {
throw new ServerError('Could not queue the pull-request resolve agent', {
status: 503,
code: 'AGENT_ACTION_UNAVAILABLE',
});
}
// `started` false means the task is persisted and queued but nothing is running
// it yet (no agent slots, daemon stopped/paused, runner unreachable) — report the
// reason rather than letting the UI claim an agent is on it. A duplicate has no
// dispatch of its own: whatever is already queued owns the run.
const started = task.dispatch?.started === true;
const queueReason = task.dispatch?.reason ?? null;
console.log(started
? `🚀 Started PR resolve agent for task ${task.id} (app ${app.id} request #${number})`
: `⏳ Queued PR resolve task ${task.id} for app ${app.id} request #${number}${queueReason ? ` — ${queueReason}` : ''}`);
res.status(task.duplicate ? 200 : 202).json({
appId: app.id,
appName: app.name,
pullRequest: { ...pullRequest, agentAction: { taskId: task.id, status: task.status } },
task: taskResponse(task),
duplicate: task.duplicate === true,
started,
queueReason,
});
}));
// POST /api/apps/:id/pull-requests/:number/merge — merge one open request NOW,
// with no agent and no model spend. The open set is re-read first, exactly as
// `/resolve` does: a tab left open for an hour must not merge a request that has
// since been closed, replaced, or turned into a draft.
router.post('/:id/pull-requests/:number/merge', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { number } = validateRequest(pullRequestParamsSchema, req.params);
const { method = DEFAULT_MERGE_METHOD, deleteBranch = false } =
validateRequest(pullRequestMergeSchema, req.body || {});
const result = await listAppPullRequests(app);
throwForgeReadError(result);
const pullRequest = findOpenPullRequest(result, number);
if (!isDirectlyMergeablePullRequest(pullRequest)) {
throw new ServerError(`${result.forge === 'gitlab' ? 'Merge' : 'Pull'} request #${number} is a draft — mark it ready for review before merging`, {
status: 409,
code: 'PULL_REQUEST_IS_DRAFT',
});
}
const merge = await mergeAppPullRequest(app, pullRequest, { method, deleteBranch });
if (!merge.ok) {
if (merge.code === 'missing-scope') throw forgeScopeMissingError(merge);
const refused = merge.code === 'method-not-allowed';
throw new ServerError(merge.error, {
// Only the forge failing the merge itself is a bad gateway; everything
// else is this request asking for something the project does not allow.
status: merge.code === 'merge-failed' ? 502 : 409,
code: refused ? 'MERGE_METHOD_NOT_ALLOWED' : 'PULL_REQUEST_MERGE_FAILED',
context: { method, reason: merge.code },
});
}
res.json({
appId: app.id,
appName: app.name,
number,
merged: true,
method: merge.method,
// The ANSWER, not the request: a long-lived head (a `main → release`
// request) merges without its branch being deleted.
deletedBranch: merge.deletedBranch,
});
}));
// POST /api/apps/:id/pull-requests/:number/review — queue the `pr-reviewer`
// scheduled task narrowed to ONE request. The scheduled task normally decides
// for itself which of the app's external PRs to sweep; a targeted request pins
// it to the row the user pressed.
//
// Eligibility and the duplicate check live in `queueTargetedPrReview`, shared
// with the GitHub notifications Autopilot hand-off. Checking now turns "the run silently produced nothing an hour later" into an
// immediate, explained refusal.
router.post('/:id/pull-requests/:number/review', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { number } = validateRequest(pullRequestParamsSchema, req.params);
// Optional provider/model/effort pin from the tab's "Run with" picker. A
// public-review posture (see resolveAgentProviderAndModel) still gates the
// provider to its own eligible set — an ineligible pin is dropped with a
// warning rather than honored, same as any other pr-reviewer pin.
const { provider, model, effort } = validateRequest(pullRequestProviderOverrideSchema, req.body || {});
const queued = await queueTargetedPrReview(app, number, { provider, model, effort });
if (queued.duplicate) {
res.json({ appId: app.id, appName: app.name, number, reviewAction: queued.reviewAction, duplicate: true });
return;
}
res.status(202).json({
appId: app.id,
appName: app.name,
number,
requestId: queued.request.id,
reviewAction: { taskId: null, status: 'pending' },
duplicate: false,
});
}));
// POST /api/apps/:id/pull-requests/:number/do-review — run the bundled
// `/do:review` workflow against ONE open request and publish its findings as an
// inline review.
//
// Deliberately NOT gated on authorship. `/review` above covers untrusted
// contributors only, and `/resolve` is the fix-and-land lifecycle, so a PR from
// a known code contributor, a teammate, or PortOS's own agents had no
// review-only action at all. Eligibility here is just "an open PR slashdo's PR
// mode can read": GitHub, with a URL.
router.post('/:id/pull-requests/:number/do-review', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { number } = validateRequest(pullRequestParamsSchema, req.params);
// Optional provider/model/effort pin from the tab's "Run with" picker, applied
// exactly as /resolve applies it: this is a directly user-triggered agent run,
// not a scheduled task with saved stage providers. The review settings ride
// along the same way — `/do:review` resolves its own roster at prompt-build
// time, so both the mode and any reviewer override are handed to the task
// rather than rendered into a flag here.
const runSettings = validateRequest(pullRequestRunSettingsSchema, req.body || {});
const { provider, model, effort } = runSettings;
// Deliberately NOT `listWithActionState`: that annotates every row with all
// four action fields, and its `resolveReviewEligibility` spends a `gh repo
// view`, a `gh api user`, and one collaborator-permission call per distinct PR
// author — for `reviewEligible`, which this route never reads. `/review` skips
// it for the same reason. The two reads are independent, so they overlap.
const [result, tasks] = await Promise.all([listAppPullRequests(app), readActiveTasks()]);
throwForgeReadError(result);
// Before any row lookup: on a non-GitHub forge every row is a guaranteed 409,
// so say so rather than searching a list that cannot produce a match.
// slashdo's PR mode aborts on a GitLab merge-request URL rather than falling
// back to a local diff, so there is nothing to burn an agent run on.
if (result.forge !== 'github') {
throw new ServerError(
`Do:Review covers GitHub pull requests only (this app's forge is ${result.forge || 'unknown'})`,
{ status: 409, code: 'PULL_REQUEST_NOT_REVIEWABLE' },
);
}
const pullRequest = findOpenPullRequest(result, number);
if (!isDoReviewablePullRequest(result, pullRequest)) {
throw new ServerError(`Pull request #${number} has no usable forge URL`, {
status: 502,
code: 'PULL_REQUEST_CONTEXT_UNAVAILABLE',
});
}
// Fail CLOSED on unreadable task state, matching /resolve and /review: reading
// it as "nothing in flight" would spend a second full review roster on a
// request an agent is already reviewing.
if (tasks === null) {
throw new ServerError('Could not inspect existing CoS actions before queueing this review', {
status: 503,
code: 'AGENT_ACTION_UNAVAILABLE',
});
}
const existing = tasks.find(task => isDoReviewTaskFor(task, app.id, pullRequest));
if (existing) {
res.json({
appId: app.id,
appName: app.name,
number,
doReviewAction: { taskId: existing.id, status: existing.status },
duplicate: true,
});
return;
}
const queued = await spawnPrDoReviewTask({
app,
pullRequest,
repoFullName: result.fullName,
provider,
model,
effort,
selfReview: isSelfReviewMode(runSettings.reviewMode),
reviewerConfig: reviewerConfigMetadata(runSettings),
});
if (!queued.task) {
throw new ServerError('Could not queue the pull-request review agent', {
status: 503,
code: 'AGENT_ACTION_UNAVAILABLE',
});
}
res.status(queued.duplicate ? 200 : 202).json({
appId: app.id,
appName: app.name,
number,
doReviewAction: { taskId: queued.task.id, status: queued.task.status },
duplicate: queued.duplicate,
// Same `started` / `queueReason` pair /resolve returns, so the tab's one
// toast builder reads both actions the same way.
started: queued.dispatch.started,
queueReason: queued.dispatch.reason,
});
}));
export default router;