@formthefog/stratus 2026.2.24 → 2026.3.19

package/.github/sentinel/src/responder.ts

@@ -0,0 +1,156 @@
+import * as core from "@actions/core"
+import * as github from "@actions/github"
+import type { ModelClient } from "./models/types"
+import type { ReviewContext, ResponseContext } from "./types"
+
+type Octokit = ReturnType<typeof github.getOctokit>
+
+const RESPOND_SYSTEM = `You are Sentinel, an AI code review bot responding to a developer's question or comment about a code review finding.
+
+Guidelines:
+1. If they point out your finding was wrong, acknowledge it clearly
+2. If they ask for clarification, provide specific code-level detail
+3. If they ask you to fix something, describe the fix precisely
+4. If they disagree, engage constructively with their reasoning
+5. Be concise and direct — developers don't want fluff
+6. Reference specific files and line numbers when relevant
+
+Do NOT output JSON. Respond in plain markdown as a conversation reply.`
+
+export async function handleResponse(
+  ctx: ReviewContext,
+  responseContext: ResponseContext,
+  model: ModelClient,
+  octokit: Octokit
+): Promise<void> {
+  const { owner, repo } = github.context.repo
+  const parentBody = await resolveParentComment(octokit, responseContext)
+
+  const contextParts: string[] = []
+
+  if (parentBody) {
+    contextParts.push(`## Original Sentinel Comment\n${parentBody}`)
+  }
+
+  if (ctx.pullRequest) {
+    contextParts.push(`## PR Context\nPR #${ctx.pullRequest.number}: ${ctx.pullRequest.title}\n${ctx.pullRequest.body || ""}`)
+  }
+
+  if (ctx.issue) {
+    contextParts.push(`## Issue Context\nIssue #${ctx.issue.number}: ${ctx.issue.title}\n${ctx.issue.body || ""}`)
+  }
+
+  const prompt = [
+    ...contextParts,
+    "",
+    "## Developer's Comment",
+    responseContext.replyBody,
+  ].join("\n\n")
+
+  core.info("Generating response to developer comment")
+
+  const result = await model.chat(RESPOND_SYSTEM, prompt)
+  const responseBody = formatResponse(result.text)
+
+  if (responseContext.isPRReviewComment) {
+    await replyToReviewComment(octokit, responseContext.commentId, responseBody)
+  } else {
+    const issueNumber = ctx.pullRequest?.number || ctx.issue?.number
+    if (issueNumber) {
+      await octokit.rest.issues.createComment({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        body: responseBody,
+      })
+    }
+  }
+
+  core.info("Response posted")
+}
+
+async function resolveParentComment(
+  octokit: Octokit,
+  responseContext: ResponseContext
+): Promise<string> {
+  if (responseContext.parentCommentBody) {
+    return responseContext.parentCommentBody
+  }
+
+  const { owner, repo } = github.context.repo
+
+  if (responseContext.isPRReviewComment) {
+    const inReplyToId = github.context.payload.comment?.in_reply_to_id
+    if (inReplyToId) {
+      try {
+        const { data: parent } = await octokit.rest.pulls.getReviewComment({
+          owner,
+          repo,
+          comment_id: inReplyToId,
+        })
+        return parent.body || ""
+      } catch {
+        core.debug(`Could not fetch parent review comment ${inReplyToId}`)
+      }
+    }
+  } else {
+    const issueNumber = github.context.payload.issue?.number
+    if (issueNumber) {
+      try {
+        const { data: comments } = await octokit.rest.issues.listComments({
+          owner,
+          repo,
+          issue_number: issueNumber,
+          per_page: 10,
+        })
+
+        for (let i = comments.length - 1; i >= 0; i--) {
+          if (comments[i].body?.includes("Sentinel") && comments[i].id !== responseContext.commentId) {
+            return comments[i].body || ""
+          }
+        }
+      } catch {
+        core.debug("Could not fetch previous comments")
+      }
+    }
+  }
+
+  return ""
+}
+
+async function replyToReviewComment(
+  octokit: Octokit,
+  commentId: number,
+  body: string
+): Promise<void> {
+  const { owner, repo } = github.context.repo
+  const prNumber = github.context.payload.pull_request?.number
+
+  if (!prNumber) {
+    core.warning("No PR number for review comment reply")
+    return
+  }
+
+  try {
+    await octokit.rest.pulls.createReplyForReviewComment({
+      owner,
+      repo,
+      pull_number: prNumber,
+      comment_id: commentId,
+      body,
+    })
+  } catch (err) {
+    core.warning(`Could not reply to review comment, posting as issue comment: ${err}`)
+    await octokit.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: prNumber,
+      body,
+    })
+  }
+}
+
+function formatResponse(text: string): string {
+  const cleaned = text.trim()
+  return `${cleaned}\n\n---\n*Sentinel*`
+}

package/.github/sentinel/src/router.ts

@@ -0,0 +1,308 @@
+import * as core from "@actions/core"
+import * as github from "@actions/github"
+import type { ActionType, EventType, SlashCommand, RoutedEvent, ReviewContext, RepoPolicies, ResponseContext } from "./types"
+
+const SLASH_COMMANDS = ["review", "fix", "triage", "plan", "explain", "retry", "ignore", "security-review", "tests"]
+const BOT_MARKER = "Sentinel"
+const TRUSTED_ASSOCIATIONS = ["MEMBER", "OWNER", "COLLABORATOR"]
+
+export function routeEvent(policies: RepoPolicies): RoutedEvent {
+  const { context } = github
+  const eventName = context.eventName
+  const action = context.payload.action || ""
+  const actor = context.actor
+
+  const pr = context.payload.pull_request
+  const isFork = pr ? pr.head?.repo?.full_name !== context.payload.repository?.full_name : false
+  const authorAssociation = (context.payload.comment?.author_association as string) || undefined
+
+  core.info(`Routing event: ${eventName} / ${action} from ${actor} (assoc=${authorAssociation || "N/A"}, fork=${isFork})`)
+
+  const baseContext: ReviewContext = {
+    repository: {
+      owner: context.repo.owner,
+      name: context.repo.repo,
+      defaultBranch: context.payload.repository?.default_branch || "main",
+    },
+    event: {
+      type: mapEventType(eventName),
+      action,
+      actor,
+      trustedActor: TRUSTED_ASSOCIATIONS.includes(authorAssociation || ""),
+      isFork,
+      authorAssociation,
+    },
+    repoPolicies: policies,
+  }
+
+  if (eventName === "pull_request") {
+    return routePullRequest(baseContext, action, policies)
+  }
+
+  if (eventName === "issues") {
+    return routeIssue(baseContext, action, policies)
+  }
+
+  if (eventName === "issue_comment") {
+    return routeComment(baseContext, policies)
+  }
+
+  if (eventName === "pull_request_review_comment") {
+    return routeReviewComment(baseContext, policies)
+  }
+
+  if (eventName === "workflow_dispatch") {
+    return { actionType: "pr_review", context: baseContext }
+  }
+
+  core.info(`Unhandled event: ${eventName}`)
+  return { actionType: "noop", context: baseContext }
+}
+
+// ── Pull Request Events ──
+
+function routePullRequest(ctx: ReviewContext, action: string, policies: RepoPolicies): RoutedEvent {
+  const pr = github.context.payload.pull_request
+  if (!pr) return { actionType: "noop", context: ctx }
+
+  const labels: string[] = (pr.labels || []).map((l: { name: string }) => l.name)
+
+  const labelGateEnabled = policies.trigger.requireLabel !== ""
+
+  if (action === "labeled") {
+    if (labelGateEnabled) {
+      const addedLabel = github.context.payload.label?.name || ""
+      if (addedLabel.toLowerCase() !== policies.trigger.requireLabel.toLowerCase()) {
+        return { actionType: "noop", context: ctx }
+      }
+    }
+  } else if (["opened", "synchronize", "reopened"].includes(action)) {
+    if (labelGateEnabled && !hasLabel(labels, policies.trigger.requireLabel)) {
+      core.info(`PR #${pr.number} missing "${policies.trigger.requireLabel}" label — skipping`)
+      return { actionType: "noop", context: ctx }
+    }
+  } else {
+    return { actionType: "noop", context: ctx }
+  }
+
+  ctx.pullRequest = {
+    number: pr.number,
+    title: pr.title || "",
+    body: pr.body || "",
+    baseRef: pr.base?.ref || "main",
+    headRef: pr.head?.ref || "",
+    labels,
+    changedFiles: [],
+  }
+
+  return { actionType: "pr_review", context: ctx }
+}
+
+// ── Issue Events ──
+
+function routeIssue(ctx: ReviewContext, action: string, policies: RepoPolicies): RoutedEvent {
+  const issue = github.context.payload.issue
+  if (!issue) return { actionType: "noop", context: ctx }
+
+  const labels: string[] = (issue.labels || []).map((l: { name: string }) => l.name)
+
+  const labelGateEnabled = policies.trigger.requireLabel !== ""
+
+  if (action === "labeled") {
+    if (labelGateEnabled) {
+      const addedLabel = github.context.payload.label?.name || ""
+      if (addedLabel.toLowerCase() !== policies.trigger.requireLabel.toLowerCase()) {
+        return { actionType: "noop", context: ctx }
+      }
+    }
+  } else if (action === "opened") {
+    if (labelGateEnabled && !hasLabel(labels, policies.trigger.requireLabel)) {
+      core.info(`Issue #${issue.number} missing "${policies.trigger.requireLabel}" label — skipping`)
+      return { actionType: "noop", context: ctx }
+    }
+  } else {
+    return { actionType: "noop", context: ctx }
+  }
+
+  ctx.issue = {
+    number: issue.number,
+    title: issue.title || "",
+    body: issue.body || "",
+    labels,
+  }
+
+  return { actionType: "issue_fix", context: ctx }
+}
+
+// ── Issue / PR Comment Events ──
+
+function routeComment(ctx: ReviewContext, policies: RepoPolicies): RoutedEvent {
+  const comment = github.context.payload.comment
+  const issue = github.context.payload.issue
+  if (!comment || !issue) return { actionType: "noop", context: ctx }
+
+  if (!ctx.event.trustedActor) {
+    core.info(`Ignoring comment from untrusted actor ${ctx.event.actor} (association: ${ctx.event.authorAssociation || "NONE"})`)
+    return { actionType: "noop", context: ctx }
+  }
+
+  const body = (comment.body || "").trim()
+  const isPR = !!issue.pull_request
+  const labels: string[] = (issue.labels || []).map((l: { name: string }) => l.name)
+  const hasAgentLabel = hasLabel(labels, policies.trigger.requireLabel)
+  const botName = policies.trigger.botName
+
+  const slashCommand = parseSlashCommand(body, ctx.event.actor, issue.number, isPR)
+  if (slashCommand) {
+    const actionType = resolveCommandAction(slashCommand, isPR)
+    attachIssueOrPR(ctx, issue, isPR)
+    return { actionType, context: ctx, slashCommand }
+  }
+
+  const mentioned = isMentioned(body, botName)
+  if (mentioned) {
+    attachIssueOrPR(ctx, issue, isPR)
+    const actionType = isPR ? "pr_review" : "issue_fix"
+    core.info(`@${botName} mentioned in comment on ${isPR ? "PR" : "issue"} #${issue.number}`)
+    return { actionType, context: ctx }
+  }
+
+  if (policies.trigger.respondToReplies && hasAgentLabel) {
+    const isReplyToBot = isBotComment(comment.body, body)
+    if (isReplyToBot) {
+      attachIssueOrPR(ctx, issue, isPR)
+      const responseContext: ResponseContext = {
+        parentCommentBody: "",
+        replyBody: body,
+        commentId: comment.id,
+        isPRReviewComment: false,
+      }
+      return { actionType: "respond", context: ctx, responseContext }
+    }
+  }
+
+  return { actionType: "noop", context: ctx }
+}
+
+// ── PR Review Comment Events (reply detection) ──
+
+function routeReviewComment(ctx: ReviewContext, policies: RepoPolicies): RoutedEvent {
+  const comment = github.context.payload.comment
+  const pr = github.context.payload.pull_request
+  if (!comment || !pr) return { actionType: "noop", context: ctx }
+
+  if (!ctx.event.trustedActor) {
+    core.info(`Ignoring review comment from untrusted actor ${ctx.event.actor} (association: ${ctx.event.authorAssociation || "NONE"})`)
+    return { actionType: "noop", context: ctx }
+  }
+
+  const body = (comment.body || "").trim()
+  const botName = policies.trigger.botName
+  const inReplyToId = comment.in_reply_to_id
+
+  ctx.pullRequest = {
+    number: pr.number,
+    title: pr.title || "",
+    body: pr.body || "",
+    baseRef: pr.base?.ref || "main",
+    headRef: pr.head?.ref || "",
+    labels: (pr.labels || []).map((l: { name: string }) => l.name),
+    changedFiles: [],
+  }
+
+  if (isMentioned(body, botName)) {
+    core.info(`@${botName} mentioned in review comment on PR #${pr.number}`)
+    return { actionType: "pr_review", context: ctx }
+  }
+
+  if (policies.trigger.respondToReplies && inReplyToId) {
+    const responseContext: ResponseContext = {
+      parentCommentBody: "",
+      replyBody: body,
+      commentId: comment.id,
+      isPRReviewComment: true,
+    }
+    return { actionType: "respond", context: ctx, responseContext }
+  }
+
+  return { actionType: "noop", context: ctx }
+}
+
+// ── Helpers ──
+
+function hasLabel(labels: string[], target: string): boolean {
+  return labels.some((l) => l.toLowerCase() === target.toLowerCase())
+}
+
+function isMentioned(body: string, botName: string): boolean {
+  return body.toLowerCase().includes(`@${botName.toLowerCase()}`)
+}
+
+function isBotComment(_commentBody: string, _body: string): boolean {
+  return false
+}
+
+function attachIssueOrPR(
+  ctx: ReviewContext,
+  issue: { number: number; title?: string; body?: string; labels?: Array<{ name: string }>; pull_request?: unknown },
+  isPR: boolean
+): void {
+  if (isPR) {
+    ctx.pullRequest = {
+      number: issue.number,
+      title: issue.title || "",
+      body: issue.body || "",
+      baseRef: "",
+      headRef: "",
+      labels: (issue.labels || []).map((l: { name: string }) => l.name),
+      changedFiles: [],
+    }
+  } else {
+    ctx.issue = {
+      number: issue.number,
+      title: issue.title || "",
+      body: issue.body || "",
+      labels: (issue.labels || []).map((l: { name: string }) => l.name),
+    }
+  }
+}
+
+function parseSlashCommand(body: string, actor: string, issueNumber: number, isPR: boolean): SlashCommand | undefined {
+  const match = body.match(/^\/bot\s+(\S+)(.*)$/m)
+  if (!match) return undefined
+
+  const command = match[1].toLowerCase()
+  if (!SLASH_COMMANDS.includes(command)) return undefined
+
+  const args = match[2].trim().split(/\s+/).filter(Boolean)
+  return { command, args, actor, issueNumber, isPR }
+}
+
+function resolveCommandAction(cmd: SlashCommand, isPR: boolean): ActionType {
+  switch (cmd.command) {
+    case "review":
+      return isPR ? "pr_review" : "noop"
+    case "fix":
+      return isPR ? "pr_fix" : "issue_fix"
+    case "triage":
+      return "issue_triage"
+    case "plan":
+    case "explain":
+      return isPR ? "pr_review" : "issue_triage"
+    case "security-review":
+    case "tests":
+      return isPR ? "pr_review" : "noop"
+    case "ignore":
+    case "retry":
+    default:
+      return "noop"
+  }
+}
+
+function mapEventType(eventName: string): EventType {
+  if (eventName === "pull_request") return "pull_request"
+  if (eventName === "issues") return "issue"
+  if (eventName === "issue_comment") return "issue_comment"
+  if (eventName === "pull_request_review_comment") return "pull_request_review_comment"
+  return "issue_comment"
+}

package/.github/sentinel/src/schemas/config.ts

@@ -0,0 +1,84 @@
+import { z } from "zod"
+
+export const SentinelConfigSchema = z.object({
+  mode: z
+    .enum([
+      "review",
+      "review_and_suggest",
+      "review_and_patch",
+      "issue_triage",
+      "issue_fix",
+      "manual_only",
+    ])
+    .default("review"),
+
+  models: z
+    .object({
+      anthropic: z
+        .object({
+          enabled: z.boolean().default(true),
+          model: z.string().default("claude-sonnet-4-20250514"),
+        })
+        .default({}),
+      openai: z
+        .object({
+          enabled: z.boolean().default(true),
+          model: z.string().default("gpt-4o"),
+        })
+        .default({}),
+    })
+    .default({}),
+
+  trigger: z
+    .object({
+      require_label: z.string().default("agent"),  // set to "" to run on every PR/issue
+      respond_to_mentions: z.boolean().default(true),
+      respond_to_replies: z.boolean().default(true),
+      bot_name: z.string().default("sentinel"),
+    })
+    .default({}),
+
+  review: z
+    .object({
+      max_files: z.number().default(50),
+      max_patch_chars: z.number().default(200_000),
+      comment_style: z.enum(["concise", "comprehensive"]).default("comprehensive"),
+      inline_comments: z.boolean().default(true),
+      severity_threshold: z
+        .enum(["low", "medium", "high", "critical"])
+        .default("medium"),
+      summary_on_clean: z.boolean().default(false),
+    })
+    .default({}),
+
+  fix: z
+    .object({
+      mode: z.enum(["propose_only", "propose_and_pr", "yolo"]).default("propose_and_pr"),
+      confidence_threshold: z.number().min(0).max(1).default(0.7),
+      max_retry_count: z.number().default(2),
+      create_draft_pr: z.boolean().default(true),
+    })
+    .default({}),
+
+  security: z
+    .object({
+      restricted_paths: z
+        .array(z.string())
+        .default([
+          ".github/workflows/**",
+          "infra/**",
+          "auth/**",
+          "payments/**",
+        ]),
+      block_fork_mutation: z.boolean().default(true),
+    })
+    .default({}),
+
+  validation: z
+    .object({
+      commands: z.array(z.string()).default([]),
+    })
+    .default({}),
+})
+
+export type SentinelConfig = z.infer<typeof SentinelConfigSchema>

package/.github/sentinel/src/schemas/fix.ts

@@ -0,0 +1,44 @@
+import { z } from "zod"
+
+export const FileChangeSchema = z.object({
+  path: z.string(),
+  action: z.enum(["modify", "create", "delete"]),
+  changes: z
+    .array(z.object({ search: z.string(), replace: z.string() }))
+    .optional(),
+  content: z.string().optional(),
+  explanation: z.string(),
+})
+
+export const FixPlanSchema = z.object({
+  analysis: z.string(),
+  fixable: z.boolean(),
+  confidence: z.number().min(0).max(1),
+  files: z.array(FileChangeSchema),
+  commit_message: z.string(),
+  test_suggestions: z.array(z.string()),
+  risk_notes: z.array(z.string()),
+})
+
+export const FixReviewSchema = z.object({
+  approved: z.boolean(),
+  confidence: z.number().min(0).max(1),
+  concerns: z.array(z.string()),
+  verdict: z.string(),
+})
+
+export function parseFixPlan(raw: string): z.infer<typeof FixPlanSchema> {
+  const json = extractJson(raw)
+  return FixPlanSchema.parse(json)
+}
+
+export function parseFixReview(raw: string): z.infer<typeof FixReviewSchema> {
+  const json = extractJson(raw)
+  return FixReviewSchema.parse(json)
+}
+
+function extractJson(text: string): unknown {
+  const match = text.match(/\{[\s\S]*\}/)
+  if (!match) throw new Error("No JSON object found in model response")
+  return JSON.parse(match[0])
+}

package/.github/sentinel/src/schemas/review.ts

@@ -0,0 +1,73 @@
+import { z } from "zod"
+
+export const FindingSeveritySchema = z.enum(["low", "medium", "high", "critical"])
+
+export const FindingTypeSchema = z.enum([
+  "bug",
+  "security",
+  "performance",
+  "maintainability",
+  "test_gap",
+  "architecture",
+])
+
+export const ReviewFindingSchema = z.object({
+  type: FindingTypeSchema,
+  severity: FindingSeveritySchema,
+  title: z.string(),
+  file: z.string(),
+  line_start: z.number().optional(),
+  line_end: z.number().optional(),
+  explanation: z.string(),
+  suggested_fix: z.string().optional(),
+  confidence: z.number().min(0).max(1),
+})
+
+export const ModelReviewSchema = z.object({
+  summary: z.string(),
+  severity: FindingSeveritySchema,
+  confidence: z.number().min(0).max(1),
+  findings: z.array(ReviewFindingSchema),
+  merge_blocking: z.boolean(),
+  needs_human_attention: z.boolean(),
+})
+
+export const CritiqueOutputSchema = z.object({
+  agreed_findings: z.array(z.string()),
+  disputed_findings: z.array(
+    z.object({ finding: z.string(), reason: z.string() })
+  ),
+  missed_issues: z.array(ReviewFindingSchema),
+  overall_assessment: z.string(),
+  revised_severity: FindingSeveritySchema,
+})
+
+export const CritiqueResponseSchema = z.object({
+  accepted: z.array(z.string()),
+  disputed: z.array(
+    z.object({ critique: z.string(), rebuttal: z.string() })
+  ),
+  revised_findings: z.array(ReviewFindingSchema),
+  final_summary: z.string(),
+})
+
+export function parseModelReview(raw: string): z.infer<typeof ModelReviewSchema> {
+  const json = extractJson(raw)
+  return ModelReviewSchema.parse(json)
+}
+
+export function parseCritiqueOutput(raw: string): z.infer<typeof CritiqueOutputSchema> {
+  const json = extractJson(raw)
+  return CritiqueOutputSchema.parse(json)
+}
+
+export function parseCritiqueResponse(raw: string): z.infer<typeof CritiqueResponseSchema> {
+  const json = extractJson(raw)
+  return CritiqueResponseSchema.parse(json)
+}
+
+function extractJson(text: string): unknown {
+  const match = text.match(/\{[\s\S]*\}/)
+  if (!match) throw new Error("No JSON object found in model response")
+  return JSON.parse(match[0])
+}