@agent-native/core 0.132.1 → 0.133.0

package/corpus/templates/factory/server/triage/ai-services-git.ts

@@ -0,0 +1,197 @@
+import type { AiServicesPullRequestSnapshot } from "./github-ingestion.js";
+import type { ReviewCommentObservation } from "./pr-babysit.js";
+import type {
+  PullRequestCheckObservation,
+  PullRequestReviewObservation,
+} from "./pr-monitor.js";
+
+export interface AiServicesGitReadClientOptions {
+  baseUrl: string;
+  authorization: string;
+  fetchImpl?: typeof fetch;
+}
+
+export interface AiServicesPullRequestLookup {
+  projectId: string;
+  repo: string;
+  pullRequestNumber: number;
+}
+
+export interface AiServicesPullRequestRead extends AiServicesPullRequestSnapshot {
+  readonly comments: readonly ReviewCommentObservation[];
+  readonly commentsTruncated: boolean;
+}
+
+// ai-services fetches exactly one uncapped page of this many review comments
+// and returns no truncated flag, so a full page is the only evidence that
+// newer comments were dropped. GitHub returns them oldest-first, so the ones
+// lost are the most likely to still be open.
+const REVIEW_COMMENT_PAGE_SIZE = 100;
+
+type JsonResponse = {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+};
+
+export function createAiServicesGitReadClient(
+  options: AiServicesGitReadClientOptions,
+) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+
+  async function get<T>(path: string, lookup: AiServicesPullRequestLookup) {
+    const url = new URL(path, `${baseUrl}/`);
+    url.searchParams.set("projectId", lookup.projectId);
+    url.searchParams.set("prNumber", String(lookup.pullRequestNumber));
+    const response = (await fetchImpl(url, {
+      headers: { Authorization: options.authorization },
+    })) as JsonResponse;
+    if (!response.ok) {
+      throw new Error(
+        `ai-services GitHub read failed for ${path}: HTTP ${response.status}`,
+      );
+    }
+    return (await response.json()) as T;
+  }
+
+  return {
+    async fetchPullRequest(
+      lookup: AiServicesPullRequestLookup,
+    ): Promise<AiServicesPullRequestRead> {
+      const [detail, reviews, checks, files] = await Promise.all([
+        get<{
+          pullRequest: {
+            title: string;
+            body: string;
+            head: { sha: string };
+            htmlUrl: string;
+            changedFiles: number;
+            additions: number;
+            deletions: number;
+          };
+        }>("/projects/git/fetch-pull-request-detail", lookup),
+        get<{
+          reviews: Array<{
+            user: { login: string };
+            state: string;
+            submittedAt: string;
+            comments?: Array<{
+              id: number;
+              user: { login: string };
+              body: string;
+              createdAt: string;
+              path?: string;
+              // GitHub sends a literal null once the line leaves the diff.
+              line?: number | null;
+              inReplyToId?: number;
+              isResolved?: boolean;
+            }>;
+          }>;
+        }>("/projects/git/fetch-pull-request-reviews", lookup),
+        get<{
+          checks: Array<{
+            name: string;
+            status: string;
+            conclusion?: string;
+            startedAt?: string;
+            completedAt?: string;
+          }>;
+        }>("/projects/git/fetch-pull-request-checks", lookup),
+        get<{
+          files: Array<{
+            filename: string;
+            additions: number;
+            deletions: number;
+          }>;
+        }>("/projects/git/fetch-pull-request-files", lookup),
+      ]);
+      const observedAt = new Date().toISOString();
+      const pullRequest = detail.pullRequest;
+      const reviewObservations: PullRequestReviewObservation[] =
+        reviews.reviews.map((review) => ({
+          author: review.user.login,
+          state: normalizeReviewState(review.state),
+          observedAt: review.submittedAt || observedAt,
+        }));
+      const reviewComments: ReviewCommentObservation[] =
+        reviews.reviews.flatMap((review) =>
+          (review.comments ?? []).map((comment) => ({
+            id: String(comment.id),
+            author: comment.user.login,
+            // `== null` on purpose: upstream omits this field on a
+            // thread-starting comment, so `=== null` would stringify undefined
+            // into "undefined" and no reply would ever match it.
+            inReplyToId:
+              comment.inReplyToId == null ? null : String(comment.inReplyToId),
+            body: comment.body,
+            path: comment.path,
+            line: comment.line ?? undefined,
+            // Never defaulted: undefined means the provider could not
+            // determine thread resolution, which is not "resolved".
+            isResolved: comment.isResolved,
+            createdAt: comment.createdAt,
+          })),
+        );
+      const checkObservations: PullRequestCheckObservation[] =
+        checks.checks.map((check) => ({
+          name: check.name,
+          state: normalizeCheckState(check.status, check.conclusion),
+          observedAt: check.completedAt || check.startedAt || observedAt,
+        }));
+
+      return {
+        repo: lookup.repo,
+        pullRequestNumber: lookup.pullRequestNumber,
+        headSha: pullRequest.head.sha,
+        title: pullRequest.title,
+        sourceUrl: pullRequest.htmlUrl,
+        summary: pullRequest.body.slice(0, 4_000),
+        changedFiles: files.files.map((file) => file.filename),
+        diffLines: files.files.reduce(
+          (total, file) => total + file.additions + file.deletions,
+          0,
+        ),
+        coverage: "complete",
+        reviews: reviewObservations,
+        checks: checkObservations,
+        comments: reviewComments,
+        commentsTruncated: reviewComments.length >= REVIEW_COMMENT_PAGE_SIZE,
+        observedAt,
+      };
+    },
+  };
+}
+
+function normalizeReviewState(
+  state: string,
+): PullRequestReviewObservation["state"] {
+  switch (state) {
+    case "APPROVED":
+      return "approved";
+    case "CHANGES_REQUESTED":
+      return "changes_requested";
+    case "PENDING":
+      return "pending";
+    default:
+      return "commented";
+  }
+}
+
+function normalizeCheckState(
+  status: string,
+  conclusion?: string,
+): PullRequestCheckObservation["state"] {
+  if (status !== "completed") {
+    return status === "in_progress" ? "in_progress" : "queued";
+  }
+  switch (conclusion) {
+    case "success":
+      return "passed";
+    case "cancelled":
+    case "timed_out":
+      return "cancelled";
+    default:
+      return "failed";
+  }
+}

package/corpus/templates/factory/server/triage/builder-executor.ts

@@ -0,0 +1,118 @@
+import { resolveConnectorSecret } from "../connectors/credentials.js";
+
+export interface BuilderExecutorInput {
+  runId: string;
+  itemId: string;
+  ownerEmail: string;
+  orgId: string;
+  repository?: string | null;
+  summary?: string | null;
+  sourceUrl?: string | null;
+}
+
+export interface BuilderExecutorResult {
+  providerTaskId?: string;
+  branchName: string;
+}
+
+function requiredEnv(
+  name: "BUILDER_AI_SERVICES_URL" | "BUILDER_PROJECT_ID" | "FACTORY_PUBLIC_URL",
+): string {
+  const value =
+    name === "BUILDER_AI_SERVICES_URL"
+      ? process.env.BUILDER_AI_SERVICES_URL // guard:allow-env-credential - non-secret deployment endpoint
+      : name === "BUILDER_PROJECT_ID"
+        ? process.env.BUILDER_PROJECT_ID // guard:allow-env-credential - non-secret deployment project id
+        : process.env.FACTORY_PUBLIC_URL; // guard:allow-env-credential - public callback origin
+  if (!value) throw new Error(`${name} is required for the Builder executor.`);
+  return value;
+}
+
+function publicCallbackUrl(runId: string): string {
+  const base = requiredEnv("FACTORY_PUBLIC_URL").replace(/\/$/, "");
+  return `${base}/_agent-native/factory/builder-callback?runId=${encodeURIComponent(runId)}`;
+}
+
+export async function startBuilderRun(
+  input: BuilderExecutorInput,
+): Promise<BuilderExecutorResult> {
+  const baseUrl = requiredEnv("BUILDER_AI_SERVICES_URL").replace(/\/$/, "");
+  const projectId = requiredEnv("BUILDER_PROJECT_ID");
+  const privateKey = await resolveConnectorSecret(
+    "BUILDER_PRIVATE_KEY",
+    input.ownerEmail,
+    {
+      orgId: input.orgId,
+    },
+  );
+  if (!privateKey) {
+    throw new Error(
+      "No Builder executor credential configured. Connect the Builder service in workspace settings or configure BUILDER_PRIVATE_KEY through the workspace resolver.",
+    );
+  }
+  const webhookSecret = await resolveConnectorSecret(
+    "FACTORY_BUILDER_WEBHOOK_SECRET",
+    input.ownerEmail,
+    { orgId: input.orgId },
+  );
+  if (!webhookSecret)
+    throw new Error(
+      "FACTORY_BUILDER_WEBHOOK_SECRET is required for signed callbacks.",
+    );
+
+  const branchName = `factory/${input.itemId.slice(0, 12)}`;
+  const prompt = [
+    "Work on this approved Factory item.",
+    input.summary
+      ? `Feedback: ${input.summary}`
+      : "No feedback summary was supplied.",
+    input.sourceUrl ? `Source: ${input.sourceUrl}` : "",
+    input.repository ? `Repository: ${input.repository}` : "",
+    "Inspect the repository, make the smallest safe fix, run validation, and open a pull request.",
+    "Do not touch protected areas: auth/session/identity, credentials/vault, migrations, payments, security, or publishable packages.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  const response = await fetch(`${baseUrl}/projects/branch/message`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${privateKey.startsWith("bpk-") ? privateKey : `bpk-${privateKey}`}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      projectId,
+      branchName,
+      userMessage: {
+        userPrompt: prompt,
+        runValidateCommand: true,
+        queue: true,
+      },
+      fireAndForget: true,
+      webhook: { url: publicCallbackUrl(input.runId), secret: webhookSecret },
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Builder executor rejected the run: HTTP ${response.status} ${await response.text()}`,
+    );
+  }
+  let payload: {
+    id?: string;
+    taskId?: string;
+    runId?: string;
+  };
+  try {
+    payload = (await response.json()) as typeof payload;
+  } catch {
+    throw new Error("Builder executor returned invalid JSON.");
+  }
+  const providerTaskId = payload.id ?? payload.taskId ?? payload.runId;
+  if (!providerTaskId) {
+    throw new Error("Builder executor response did not include a task id.");
+  }
+  return {
+    providerTaskId,
+    branchName,
+  };
+}

package/corpus/templates/factory/server/triage/contracts.ts

@@ -0,0 +1,164 @@
+import { z } from "zod";
+
+export const triageSourceSchema = z.enum(["slack", "github"]);
+export type TriageSource = z.infer<typeof triageSourceSchema>;
+
+export const triageItemStatusSchema = z.enum([
+  "received",
+  "context_fetching",
+  "evidence_ready",
+  "classified",
+  "shadow_decided",
+  "needs_manual",
+  "failed",
+  "reconciliation_required",
+]);
+export type TriageItemStatus = z.infer<typeof triageItemStatusSchema>;
+
+export const triageRiskSchema = z.enum([
+  "unknown",
+  "low",
+  "medium",
+  "high",
+  "critical",
+]);
+export type TriageRisk = z.infer<typeof triageRiskSchema>;
+
+export const triageCoverageSchema = z.enum([
+  "complete",
+  "partial",
+  "unknown",
+  "unavailable",
+]);
+export type TriageCoverage = z.infer<typeof triageCoverageSchema>;
+
+export const triageDecisionOutcomeSchema = z.enum([
+  "observe",
+  "needs_manual",
+  "propose_fix",
+  "propose_review",
+]);
+export type TriageDecisionOutcome = z.infer<typeof triageDecisionOutcomeSchema>;
+
+export const triageRuleModeSchema = z.enum(["disabled", "shadow"]);
+export type TriageRuleMode = z.infer<typeof triageRuleModeSchema>;
+
+export const executorStateSchema = z.enum([
+  "submitted",
+  "acknowledged",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+  "timed_out",
+  "reconciliation_required",
+]);
+export type ExecutorState = z.infer<typeof executorStateSchema>;
+
+export const triageGuardCodeSchema = z.enum([
+  "auth",
+  "session",
+  "identity",
+  "credentials",
+  "vault",
+  "migration",
+  "payments",
+  "security",
+  "publishable_package",
+  "path_denied",
+  "diff_too_large",
+  "unknown_change",
+]);
+export type TriageGuardCode = z.infer<typeof triageGuardCodeSchema>;
+
+export const hardNeverAutomateGuardCodes: TriageGuardCode[] = [
+  "auth",
+  "session",
+  "identity",
+  "credentials",
+  "vault",
+  "migration",
+  "payments",
+  "security",
+  "publishable_package",
+];
+
+export const triagePolicyGuardsSchema = z.object({
+  allowRepositories: z.array(z.string().min(1)).default([]),
+  denyPathPrefixes: z.array(z.string().min(1)).default([]),
+  maxChangedFiles: z.number().int().positive().nullable().default(30),
+  maxDiffLines: z.number().int().positive().nullable().default(1500),
+  neverAutomate: z
+    .array(triageGuardCodeSchema)
+    .default(hardNeverAutomateGuardCodes),
+});
+
+export interface GuardResult {
+  code: TriageGuardCode;
+  passed: boolean;
+  reason: string;
+}
+
+export interface TriagePolicyGuards {
+  allowRepositories: string[];
+  denyPathPrefixes: string[];
+  maxChangedFiles: number | null;
+  maxDiffLines: number | null;
+  neverAutomate: TriageGuardCode[];
+}
+
+export interface IngestionEnvelope {
+  source: TriageSource;
+  externalId: string;
+  receivedAt: string;
+  sourceUrl?: string;
+  title: string;
+  summary?: string;
+  channelId?: string;
+  threadTs?: string;
+  repository?: string;
+  pullRequestNumber?: number;
+  headSha?: string;
+  coverage: TriageCoverage;
+  metadata?: Record<string, string | number | boolean | string[] | null>;
+}
+
+export interface ExecutorTaskContract {
+  id: string;
+  triageItemId: string;
+  dedupeKey: string;
+  state: ExecutorState;
+  provider: "builder-http" | "harness" | "a2a" | "bot-tag";
+  providerTaskId?: string;
+  terminalReason?: string;
+  observedAt: string;
+}
+
+export function normalizeTriagePolicyGuards(
+  value: unknown,
+): TriagePolicyGuards {
+  const parsed = triagePolicyGuardsSchema.parse(value);
+  return {
+    ...parsed,
+    neverAutomate: [
+      ...new Set([...hardNeverAutomateGuardCodes, ...parsed.neverAutomate]),
+    ],
+  };
+}
+
+export function defaultTriagePolicyGuards(): TriagePolicyGuards {
+  return normalizeTriagePolicyGuards({
+    allowRepositories: [],
+    denyPathPrefixes: [
+      ".env",
+      "auth",
+      "credentials",
+      "migrations",
+      "payments",
+      "security",
+      "packages/",
+    ],
+    maxChangedFiles: 30,
+    maxDiffLines: 1500,
+  });
+}

package/corpus/templates/factory/server/triage/github-ingestion.ts

@@ -0,0 +1,35 @@
+import type { IngestionEnvelope } from "./contracts.js";
+import type { PullRequestObservation } from "./pr-monitor.js";
+
+export interface AiServicesPullRequestSnapshot extends PullRequestObservation {
+  readonly title: string;
+  readonly sourceUrl?: string;
+  readonly summary?: string;
+  readonly changedFiles?: readonly string[];
+  readonly diffLines?: number;
+  readonly coverage: "complete" | "partial" | "unknown" | "unavailable";
+}
+
+export function pullRequestSnapshotToEnvelope(
+  snapshot: AiServicesPullRequestSnapshot,
+): IngestionEnvelope {
+  const externalId = `${snapshot.repo}#${snapshot.pullRequestNumber}@${snapshot.headSha}`;
+  return {
+    source: "github",
+    externalId,
+    receivedAt: snapshot.observedAt,
+    ...(snapshot.sourceUrl ? { sourceUrl: snapshot.sourceUrl } : {}),
+    title: snapshot.title,
+    summary: snapshot.summary,
+    repository: snapshot.repo,
+    pullRequestNumber: snapshot.pullRequestNumber,
+    headSha: snapshot.headSha,
+    coverage: snapshot.coverage,
+    metadata: {
+      changedFiles: snapshot.changedFiles ? [...snapshot.changedFiles] : null,
+      diffLines: snapshot.diffLines ?? null,
+      reviews: snapshot.reviews.length,
+      checks: snapshot.checks.length,
+    },
+  };
+}

package/corpus/templates/factory/server/triage/guards.ts

@@ -0,0 +1,121 @@
+import type {
+  GuardResult,
+  TriageGuardCode,
+  TriagePolicyGuards,
+} from "./contracts.js";
+
+export function evaluateStructuredGuards(
+  guards: TriagePolicyGuards,
+  input: {
+    repository?: string;
+    changedFiles?: string[];
+    diffLines?: number;
+    risk?: string;
+    categories?: TriageGuardCode[];
+  },
+): GuardResult[] {
+  const results: GuardResult[] = [];
+
+  for (const category of input.categories ?? []) {
+    if (guards.neverAutomate.includes(category)) {
+      results.push({
+        code: category,
+        passed: false,
+        reason: `The ${category} category is always human-gated.`,
+      });
+    }
+  }
+
+  if (guards.allowRepositories.length > 0) {
+    results.push({
+      code: "unknown_change",
+      passed:
+        !!input.repository &&
+        guards.allowRepositories.includes(input.repository),
+      reason: input.repository
+        ? `Repository ${input.repository} is not in the allowlist.`
+        : "Repository is unavailable.",
+    });
+  }
+
+  const changedFiles = input.changedFiles ?? [];
+  const deniedPath = changedFiles.find((file) =>
+    guards.denyPathPrefixes.some((prefix) => file.startsWith(prefix)),
+  );
+  if (deniedPath) {
+    results.push({
+      code: guardCodeForPath(deniedPath),
+      passed: false,
+      reason: `Sensitive path is present: ${deniedPath}`,
+    });
+  }
+
+  if (
+    guards.maxChangedFiles !== null &&
+    changedFiles.length > guards.maxChangedFiles
+  ) {
+    results.push({
+      code: "diff_too_large",
+      passed: false,
+      reason: `${changedFiles.length} changed files exceeds the limit of ${guards.maxChangedFiles}.`,
+    });
+  }
+
+  if (
+    guards.maxDiffLines !== null &&
+    typeof input.diffLines === "number" &&
+    input.diffLines > guards.maxDiffLines
+  ) {
+    results.push({
+      code: "diff_too_large",
+      passed: false,
+      reason: `${input.diffLines} diff lines exceeds the limit of ${guards.maxDiffLines}.`,
+    });
+  }
+
+  if (input.risk === "high" || input.risk === "critical") {
+    results.push({
+      code: "security",
+      passed: false,
+      reason: `Risk ${input.risk} is always human-gated in shadow mode.`,
+    });
+  }
+
+  if (results.length === 0) {
+    const hasEvidence = Boolean(
+      input.repository ||
+      (input.changedFiles && input.changedFiles.length > 0) ||
+      input.diffLines !== undefined ||
+      (input.risk && input.risk !== "unknown"),
+    );
+    results.push({
+      code: "unknown_change",
+      passed: hasEvidence,
+      reason: hasEvidence
+        ? "Structured evidence was available and no deny guard matched."
+        : "Insufficient structured evidence for an autonomous proposal.",
+    });
+  }
+
+  return results;
+}
+
+function guardCodeForPath(path: string): TriageGuardCode {
+  const normalized = path.toLowerCase();
+  if (normalized.startsWith("packages/")) return "publishable_package";
+  if (normalized.includes("migration")) return "migration";
+  if (normalized.includes("credential") || normalized.startsWith(".env")) {
+    return "credentials";
+  }
+  if (normalized.includes("vault")) return "vault";
+  if (normalized.includes("payment")) return "payments";
+  if (normalized.includes("security")) return "security";
+  if (
+    normalized.includes("auth") ||
+    normalized.includes("session") ||
+    normalized.includes("identity")
+  ) {
+    return "auth";
+  }
+  return "path_denied";
+}

package/corpus/templates/factory/server/triage/ids.ts

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+
+export function stableId(...parts: string[]): string {
+  return createHash("sha256").update(parts.join("\u001f")).digest("hex");
+}
+
+export function itemDedupeKey(
+  input: {
+    source: string;
+    externalId: string;
+    repository?: string;
+    pullRequestNumber?: number;
+    headSha?: string;
+  },
+  organizationId = "",
+): string {
+  return stableId(
+    organizationId,
+    input.source,
+    input.externalId,
+    input.repository ?? "",
+    input.pullRequestNumber === undefined
+      ? ""
+      : String(input.pullRequestNumber),
+    input.headSha ?? "",
+  );
+}