@agent-native/core 0.132.2 → 0.133.1

package/corpus/templates/factory/actions/babysit-pull-request.ts

@@ -0,0 +1,126 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { resolveConnectorSecret } from "../server/connectors/credentials.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+import { createAiServicesGitReadClient } from "../server/triage/ai-services-git.js";
+import { reconcileBabysitState } from "../server/triage/pr-babysit.js";
+import type {
+  ReviewCommentObservation,
+  BabysitProposal,
+} from "../server/triage/pr-babysit.js";
+import type { PullRequestCheckObservation } from "../server/triage/pr-monitor.js";
+
+const checkSchema: z.ZodType<PullRequestCheckObservation> = z.object({
+  name: z.string().min(1),
+  state: z.enum(["queued", "in_progress", "passed", "failed", "cancelled"]),
+  observedAt: z.string().datetime(),
+});
+
+export interface FetchReviewCommentsInput {
+  repo: string;
+  pullRequestNumber: number;
+  ownerEmail: string;
+  orgId: string;
+}
+
+export type FetchReviewComments = (input: FetchReviewCommentsInput) => Promise<{
+  comments: readonly ReviewCommentObservation[];
+  truncated: boolean;
+}>;
+
+// Same non-secret deployment endpoint/project id the Builder executor reads
+// (server/triage/builder-executor.ts); that resolver is private to this file
+// and out of scope to export, so this is a second, identical read site for
+// the same two env vars rather than a new credential path.
+function requiredAiServicesEnv(
+  name: "BUILDER_AI_SERVICES_URL" | "BUILDER_PROJECT_ID",
+): string {
+  const value =
+    name === "BUILDER_AI_SERVICES_URL"
+      ? process.env.BUILDER_AI_SERVICES_URL // guard:allow-env-credential - non-secret deployment endpoint
+      : process.env.BUILDER_PROJECT_ID; // guard:allow-env-credential - non-secret deployment project id
+  if (!value) {
+    throw new Error(
+      `review-comment fetch not configured: ${name} is required to read GitHub review comments.`,
+    );
+  }
+  return value;
+}
+
+const fetchReviewCommentsFromAiServices: FetchReviewComments = async ({
+  repo,
+  pullRequestNumber,
+  ownerEmail,
+  orgId,
+}) => {
+  const baseUrl = requiredAiServicesEnv("BUILDER_AI_SERVICES_URL");
+  const projectId = requiredAiServicesEnv("BUILDER_PROJECT_ID");
+  const privateKey = await resolveConnectorSecret(
+    "BUILDER_PRIVATE_KEY",
+    ownerEmail,
+    { orgId },
+  );
+  if (!privateKey) {
+    throw new Error(
+      "review-comment fetch not configured: no Builder executor credential (BUILDER_PRIVATE_KEY) is available for this workspace.",
+    );
+  }
+
+  const client = createAiServicesGitReadClient({
+    baseUrl,
+    authorization: `Bearer ${privateKey.startsWith("bpk-") ? privateKey : `bpk-${privateKey}`}`,
+  });
+  // Review comments ride along on the reviews read; there is no separate
+  // comments endpoint in ai-services.
+  const snapshot = await client.fetchPullRequest({
+    projectId,
+    repo,
+    pullRequestNumber,
+  });
+  return {
+    comments: snapshot.comments,
+    truncated: snapshot.commentsTruncated,
+  };
+};
+
+export function createBabysitPullRequestAction(
+  fetchComments: FetchReviewComments = fetchReviewCommentsFromAiServices,
+) {
+  return defineAction({
+    description:
+      "Propose a babysit-PR status (unanswered review comments, failing/pending checks, missing changeset packages) for one pull request. Read-only and proposal-only: never replies, pushes, merges, assigns, or invokes an executor.",
+    schema: z.object({
+      repo: z.string().trim().min(1).max(256),
+      pullRequestNumber: z.number().int().positive(),
+      checks: z.array(checkSchema).max(500).default([]),
+      failingJobLog: z.string().max(50_000).optional(),
+      botAuthors: z.array(z.string().trim().min(1)).max(50).optional(),
+    }),
+    http: false,
+    readOnly: true,
+    run: async (input, context): Promise<BabysitProposal> => {
+      const { userEmail, orgId } = await requireWorkspaceMember(
+        workspaceMemberIdentityFromContext(context),
+      );
+      const { comments, truncated } = await fetchComments({
+        repo: input.repo,
+        pullRequestNumber: input.pullRequestNumber,
+        ownerEmail: userEmail,
+        orgId,
+      });
+      return reconcileBabysitState({
+        comments,
+        checks: input.checks,
+        failingJobLog: input.failingJobLog,
+        botAuthors: input.botAuthors,
+        commentsTruncated: truncated,
+      });
+    },
+  });
+}
+
+export default createBabysitPullRequestAction();

package/corpus/templates/factory/actions/evaluate-triage-item.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+
+import { defineAction } from "@agent-native/core/action";
+import { classifyAgentFailure } from "@agent-native/core/agent/engine";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import {
+  triageDecisions,
+  triageItems,
+  triageRules,
+} from "../server/db/schema.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+import {
+  normalizeTriagePolicyGuards,
+  triageGuardCodeSchema,
+} from "../server/triage/contracts.js";
+import { evaluateStructuredGuards } from "../server/triage/guards.js";
+
+export default defineAction({
+  description:
+    "Triage one Factory item against enabled rules and append structured guard decisions. This records proposals only and never changes a provider.",
+  schema: z.object({ itemId: z.string().min(1) }),
+  http: { method: "POST" },
+  run: async ({ itemId }, context) => {
+    const { userEmail, orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const db = getDb();
+    const item = (
+      await db
+        .select()
+        .from(triageItems)
+        .where(and(eq(triageItems.id, itemId), eq(triageItems.orgId, orgId)))
+        .limit(1)
+    )[0];
+    if (!item) throw new Error("Triage item not found");
+
+    const rules = await db
+      .select()
+      .from(triageRules)
+      .where(and(eq(triageRules.orgId, orgId), eq(triageRules.enabled, 1)));
+    const metadata = parseMetadata(item.metadataJson);
+    const evidence = {
+      repository: item.repository ?? undefined,
+      changedFiles: parseStringArray(metadata.changedFiles),
+      diffLines: parseOptionalNumber(metadata.diffLines),
+      risk: item.risk,
+      categories: parseGuardCategories(metadata.categories),
+    };
+    const failureTaxonomy = classifyAgentFailure({
+      errorCode: metadata.errorCode,
+      errorDetail: [item.title, item.summary, metadata.failureText]
+        .filter((value): value is string => typeof value === "string")
+        .join("\n"),
+      terminalReason: metadata.terminalReason,
+      terminalEvent: metadata.terminalEvent,
+      regime:
+        metadata.regime === "scheduled" || metadata.regime === "interactive"
+          ? metadata.regime
+          : undefined,
+    });
+    const taxonomyReason =
+      failureTaxonomy.code === "unknown"
+        ? ""
+        : `Observed failure taxonomy: ${failureTaxonomy.label} (${failureTaxonomy.code}; ${failureTaxonomy.regime}). `;
+
+    if (rules.length === 0) {
+      return {
+        ok: true,
+        itemId,
+        evaluated: 0,
+        reason: "No enabled shadow rules.",
+      };
+    }
+
+    const now = new Date().toISOString();
+    const decisions = rules.map((rule) => {
+      const guards = normalizeTriagePolicyGuards(
+        parseObject(JSON.parse(rule.guardsJson), "guards"),
+      );
+      const guardResults = evaluateStructuredGuards(guards, evidence);
+      const outcome = guardResults.every((guard) => guard.passed)
+        ? "observe"
+        : "needs_manual";
+      return {
+        id: randomUUID(),
+        itemId,
+        ruleId: rule.id,
+        mode: rule.mode,
+        outcome,
+        reason:
+          taxonomyReason + guardResults.map((guard) => guard.reason).join(" "),
+        guardResultsJson: JSON.stringify(guardResults),
+        model: "structured-guards+failure-taxonomy",
+        promptVersion: rule.promptVersion,
+        createdAt: now,
+        ownerEmail: userEmail,
+        orgId,
+      };
+    });
+
+    await db.transaction(async (tx) => {
+      await tx.insert(triageDecisions).values(decisions);
+      await tx
+        .update(triageItems)
+        .set({
+          status: decisions.some(
+            (decision) => decision.outcome === "needs_manual",
+          )
+            ? "needs_manual"
+            : "shadow_decided",
+          updatedAt: now,
+        })
+        .where(and(eq(triageItems.id, itemId), eq(triageItems.orgId, orgId)));
+    });
+
+    return {
+      ok: true,
+      itemId,
+      evaluated: decisions.length,
+      decisionIds: decisions.map((decision) => decision.id),
+    };
+  },
+});
+
+function parseMetadata(value: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("Triage item metadata is unreadable.");
+  }
+  return parseObject(parsed, "metadata");
+}
+
+function parseObject(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Triage ${label} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseStringArray(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (
+    !Array.isArray(value) ||
+    !value.every((entry) => typeof entry === "string")
+  ) {
+    throw new Error("Triage changedFiles metadata is unreadable.");
+  }
+  return value;
+}
+
+function parseOptionalNumber(value: unknown): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error("Triage diffLines metadata is unreadable.");
+  }
+  return value;
+}
+
+function parseGuardCategories(value: unknown) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value))
+    throw new Error("Triage categories metadata is unreadable.");
+  return value.map((entry) => triageGuardCodeSchema.parse(entry));
+}

package/corpus/templates/factory/actions/get-factory-graph.ts

@@ -0,0 +1,62 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  defaultFactoryDefinition,
+  DEFAULT_FACTORY_ID,
+  parseFactoryGraph,
+  readFactoryDefinition,
+  readFactoryMetrics,
+} from "../server/factory-graph/store.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+
+export default defineAction({
+  description:
+    "Read the selected Factory's deterministic graph, version, comments target, and live evidence metrics.",
+  schema: z.object({
+    factoryId: z.string().trim().min(1).max(120).default(DEFAULT_FACTORY_ID),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ factoryId }, context) => {
+    const { orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const row = await readFactoryDefinition(orgId, factoryId);
+    const fallback = defaultFactoryDefinition();
+    const graph = row ? parseFactoryGraph(row.graphJson) : fallback.graph;
+    const metrics = await readFactoryMetrics(orgId);
+
+    const metricValues: Record<string, number> = {
+      items: metrics.totalItems,
+      slack: metrics.slackItems,
+      github: metrics.githubItems,
+      decisions: metrics.decisions,
+      needs_manual: metrics.manualItems,
+      runs: metrics.runs,
+      completed: metrics.completedRuns,
+    };
+
+    return {
+      factory: {
+        id: factoryId,
+        name: row?.name ?? fallback.name,
+        description: row?.description ?? fallback.description,
+        prompt: row?.prompt ?? fallback.prompt,
+        graphVersion: row?.graphVersion ?? graph.version,
+        virtual: !row,
+      },
+      graph,
+      metrics,
+      nodeMetrics: Object.fromEntries(
+        graph.nodes.map((node) => [
+          node.id,
+          metricValues[node.metricsKey ?? ""] ?? 0,
+        ]),
+      ),
+    };
+  },
+});

package/corpus/templates/factory/actions/get-triage-config.ts

@@ -0,0 +1,42 @@
+import { defineAction } from "@agent-native/core/action";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import { triageConfig } from "../server/db/schema.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+
+export default defineAction({
+  description:
+    "Read Factory observation settings for the active workspace. Secret values are never returned.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_, context) => {
+    const { orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const row = (
+      await getDb()
+        .select()
+        .from(triageConfig)
+        .where(eq(triageConfig.id, orgId))
+        .limit(1)
+    )[0];
+    if (!row) {
+      return {
+        slackWorkspace: "primary",
+        slackChannelId: null,
+        slackChannelName: null,
+        pollingEnabled: false,
+        lastSlackTs: null,
+        slackHistoryCursor: null,
+        repository: null,
+      };
+    }
+    return { ...row, pollingEnabled: row.pollingEnabled === 1 };
+  },
+});

package/corpus/templates/factory/actions/get-triage-item.ts

@@ -0,0 +1,74 @@
+import { defineAction } from "@agent-native/core/action";
+import { and, asc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import {
+  triageDecisions,
+  triageFeedback,
+  triageItems,
+  triageRuns,
+} from "../server/db/schema.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+
+export default defineAction({
+  description:
+    "Inspect one Factory item, including its append-only shadow decisions, feedback, and run reconciliation state.",
+  schema: z.object({ itemId: z.string().min(1) }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ itemId }, context) => {
+    const { orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const db = getDb();
+    const item = (
+      await db
+        .select()
+        .from(triageItems)
+        .where(and(eq(triageItems.id, itemId), eq(triageItems.orgId, orgId)))
+        .limit(1)
+    )[0];
+    if (!item) throw new Error("Triage item not found");
+
+    const decisions = await db
+      .select()
+      .from(triageDecisions)
+      .where(
+        and(
+          eq(triageDecisions.itemId, itemId),
+          eq(triageDecisions.orgId, orgId),
+        ),
+      )
+      .orderBy(asc(triageDecisions.createdAt));
+    const feedback = await db
+      .select()
+      .from(triageFeedback)
+      .where(eq(triageFeedback.orgId, orgId))
+      .orderBy(asc(triageFeedback.createdAt));
+    const runs = await db
+      .select()
+      .from(triageRuns)
+      .where(and(eq(triageRuns.itemId, itemId), eq(triageRuns.orgId, orgId)))
+      .orderBy(asc(triageRuns.startedAt));
+
+    return {
+      ...item,
+      decisions: decisions.map((decision) => ({
+        decisionId: decision.id,
+        outcome: decision.outcome,
+        summary: decision.reason,
+        reason: decision.reason,
+        mode: decision.mode,
+        createdAt: decision.createdAt,
+      })),
+      feedback: feedback.filter((entry) =>
+        decisions.some((decision) => decision.id === entry.decisionId),
+      ),
+      runs,
+    };
+  },
+});

package/corpus/templates/factory/actions/hello.ts

@@ -0,0 +1,13 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return a friendly greeting.",
+  schema: z.object({
+    name: z.string().default("world").describe("Name to greet"),
+  }),
+  http: { method: "GET" },
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});

package/corpus/templates/factory/actions/ingest-github-observation.ts

@@ -0,0 +1,100 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import { triageItems } from "../server/db/schema.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+import { pullRequestSnapshotToEnvelope } from "../server/triage/github-ingestion.js";
+import { itemDedupeKey } from "../server/triage/ids.js";
+import type {
+  PullRequestCheckObservation,
+  PullRequestReviewObservation,
+} from "../server/triage/pr-monitor.js";
+
+const reviewSchema: z.ZodType<PullRequestReviewObservation> = z.object({
+  author: z.string().min(1),
+  state: z.enum(["approved", "changes_requested", "commented", "pending"]),
+  observedAt: z.string().datetime(),
+});
+
+const checkSchema: z.ZodType<PullRequestCheckObservation> = z.object({
+  name: z.string().min(1),
+  state: z.enum(["queued", "in_progress", "passed", "failed", "cancelled"]),
+  observedAt: z.string().datetime(),
+});
+
+export default defineAction({
+  description:
+    "Ingest one read-only GitHub pull-request observation from the existing ai-services boundary into Factory. This action records evidence only and never writes to GitHub.",
+  schema: z.object({
+    repo: z.string().trim().min(1).max(256),
+    pullRequestNumber: z.number().int().positive(),
+    headSha: z.string().trim().min(1).max(128),
+    title: z.string().trim().min(1).max(500),
+    sourceUrl: z.string().url().optional(),
+    summary: z.string().trim().max(4_000).optional(),
+    changedFiles: z.array(z.string().max(500)).max(500).optional(),
+    diffLines: z.number().int().nonnegative().optional(),
+    coverage: z.enum(["complete", "partial", "unknown", "unavailable"]),
+    reviews: z.array(reviewSchema).max(500).default([]),
+    checks: z.array(checkSchema).max(500).default([]),
+    observedAt: z.string().datetime(),
+  }),
+  http: false,
+  agentTool: false,
+  run: async (input, context) => {
+    const { userEmail, orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const envelope = pullRequestSnapshotToEnvelope(input);
+    const id = itemDedupeKey(envelope, orgId);
+    const now = new Date().toISOString();
+    const db = getDb();
+
+    await db
+      .insert(triageItems)
+      .values({
+        id,
+        source: envelope.source,
+        externalId: envelope.externalId,
+        sourceUrl: envelope.sourceUrl ?? null,
+        title: envelope.title,
+        summary: envelope.summary ?? null,
+        status: "evidence_ready",
+        risk: "unknown",
+        repository: envelope.repository ?? null,
+        pullRequestNumber: envelope.pullRequestNumber ?? null,
+        headSha: envelope.headSha ?? null,
+        coverage: envelope.coverage,
+        dedupeKey: id,
+        metadataJson: JSON.stringify(envelope.metadata ?? {}),
+        lastSeenAt: envelope.receivedAt,
+        createdAt: now,
+        updatedAt: now,
+        ownerEmail: userEmail,
+        orgId,
+      })
+      .onConflictDoUpdate({
+        target: triageItems.id,
+        set: {
+          sourceUrl: envelope.sourceUrl ?? null,
+          title: envelope.title,
+          summary: envelope.summary ?? null,
+          coverage: envelope.coverage,
+          metadataJson: JSON.stringify(envelope.metadata ?? {}),
+          lastSeenAt: envelope.receivedAt,
+          updatedAt: now,
+        },
+      });
+
+    return {
+      ok: true,
+      id,
+      source: envelope.source,
+      coverage: envelope.coverage,
+    };
+  },
+});

package/corpus/templates/factory/actions/list-factories.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+import {
+  defaultFactoryDefinition,
+  listFactoryDefinitions,
+} from "../server/factory-graph/store.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+
+export default defineAction({
+  description:
+    "List the saved Factory definitions in the active workspace, including the default product-feedback Factory when it has not been persisted yet.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (_, context) => {
+    const { orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    const rows = await listFactoryDefinitions(orgId);
+    if (rows.some((row) => row.id === defaultFactoryDefinition().id)) {
+      return rows;
+    }
+    return [
+      {
+        id: defaultFactoryDefinition().id,
+        name: defaultFactoryDefinition().name,
+        description: defaultFactoryDefinition().description,
+        prompt: defaultFactoryDefinition().prompt,
+        graphVersion: 1,
+        updatedAt: null,
+        virtual: true,
+      },
+      ...rows,
+    ];
+  },
+});

package/corpus/templates/factory/actions/list-factory-comments.ts

@@ -0,0 +1,40 @@
+import { defineAction } from "@agent-native/core/action";
+import { and, desc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb } from "../server/db/index.js";
+import { factoryComments } from "../server/db/schema.js";
+import { DEFAULT_FACTORY_ID } from "../server/factory-graph/store.js";
+import {
+  requireWorkspaceMember,
+  workspaceMemberIdentityFromContext,
+} from "../server/lib/require-workspace-member.js";
+
+export default defineAction({
+  description:
+    "List comments attached to the selected Factory canvas, node, or edge.",
+  schema: z.object({
+    factoryId: z.string().trim().min(1).max(120).default(DEFAULT_FACTORY_ID),
+    graphVersion: z.coerce.number().int().positive().optional(),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ factoryId, graphVersion }, context) => {
+    const { orgId } = await requireWorkspaceMember(
+      workspaceMemberIdentityFromContext(context),
+    );
+    return getDb()
+      .select()
+      .from(factoryComments)
+      .where(
+        and(
+          eq(factoryComments.factoryId, factoryId),
+          eq(factoryComments.orgId, orgId),
+          ...(graphVersion
+            ? [eq(factoryComments.graphVersion, graphVersion)]
+            : []),
+        ),
+      )
+      .orderBy(desc(factoryComments.createdAt));
+  },
+});