@agent-native/core 0.90.2 → 0.90.4

package/corpus/core/src/review/actions/consume-review-feedback.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertReviewableResourceAccess } from "../registry.js";
+import { consumeReviewFeedback } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  commentIds: z.array(z.string().min(1)).min(1),
+});
+
+export default defineAction({
+  description:
+    "Mark review feedback as consumed by the agent or reviewer workflow.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "editor",
+    );
+    const updatedCount = await consumeReviewFeedback(
+      args.commentIds,
+      undefined,
+      {
+        resourceType: args.resourceType,
+        resourceId: args.resourceId,
+      },
+    );
+    if (updatedCount < 1) {
+      throw new Error("No matching review comments to consume");
+    }
+    return {
+      consumedCommentIds: args.commentIds,
+      updatedCount,
+    };
+  },
+  audit: {
+    target: (args) => ({
+      type: args.resourceType,
+      id: args.resourceId,
+    }),
+  },
+});

package/corpus/core/src/review/actions/create-review-comment.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { extractReviewMentions, normalizeReviewMentions } from "../mentions.js";
+import {
+  assertReviewableResourceAccess,
+  normalizeReviewVisibility,
+} from "../registry.js";
+import { insertReviewComment } from "../store.js";
+import type {
+  ReviewActorKind,
+  ReviewCommentKind,
+  ReviewResourceContext,
+} from "../types.js";
+
+const mentionSchema = z.object({
+  label: z.string().min(1),
+  email: z.string().email().nullable().optional(),
+  id: z.string().nullable().optional(),
+});
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  targetId: z.string().nullable().optional(),
+  kind: z
+    .enum([
+      "comment",
+      "annotation",
+      "correction",
+      "question",
+      "decision",
+      "review",
+    ])
+    .optional(),
+  anchor: z.unknown().nullable().optional(),
+  body: z.string().min(1),
+  authorName: z.string().nullable().optional(),
+  resolutionTarget: z.enum(["agent", "human"]).nullable().optional(),
+  mentions: z.array(mentionSchema).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export default defineAction({
+  description:
+    "Create an inline comment, annotation, or review thread for a resource.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    const access = await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    const mentions = normalizeReviewMentions([
+      ...normalizeReviewMentions(args.mentions),
+      ...extractReviewMentions(args.body),
+    ]);
+    const resolutionTarget =
+      args.resolutionTarget ?? (mentions.length > 0 ? "human" : "agent");
+
+    return insertReviewComment({
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      targetId: args.targetId ?? null,
+      kind: (args.kind ?? "comment") as ReviewCommentKind,
+      anchor: args.anchor ?? null,
+      body: args.body,
+      authorEmail: actionCtx?.userEmail ?? null,
+      authorName: args.authorName ?? actionCtx?.userEmail ?? null,
+      createdBy: actorKindFromContext(actionCtx),
+      resolutionTarget,
+      mentions,
+      ownerEmail: access.ownerEmail ?? actionCtx?.userEmail ?? null,
+      orgId: access.orgId ?? actionCtx?.orgId ?? null,
+      visibility: normalizeReviewVisibility(access.visibility),
+      metadata: args.metadata,
+    });
+  },
+  audit: {
+    target: (args, result) => {
+      const comment = result as {
+        ownerEmail?: string | null;
+        orgId?: string | null;
+        visibility?: "private" | "org" | "public";
+      };
+      return {
+        type: args.resourceType,
+        id: args.resourceId,
+        ownerEmail: comment.ownerEmail,
+        orgId: comment.orgId,
+        visibility: comment.visibility,
+      };
+    },
+  },
+});
+
+function actorKindFromContext(
+  ctx: ReviewResourceContext | undefined,
+): ReviewActorKind {
+  const caller = typeof ctx?.caller === "string" ? ctx.caller : "";
+  if (caller === "agent" || caller === "tool") {
+    return "agent";
+  }
+  return ctx?.userEmail ? "human" : "system";
+}

package/corpus/core/src/review/actions/delete-review-comment.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { ForbiddenError } from "../../sharing/access.js";
+import { roleSatisfies } from "../../sharing/schema.js";
+import { resolveReviewableResourceAccess } from "../registry.js";
+import { deleteReviewComment, getReviewCommentById } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  commentId: z.string().min(1),
+});
+
+export default defineAction({
+  description: "Soft-delete a review comment.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const access = await resolveReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+    );
+    const comment = await getReviewCommentById(args.commentId, scope, {
+      bypassScope: Boolean(access),
+    });
+    if (
+      !comment ||
+      comment.resourceType !== args.resourceType ||
+      comment.resourceId !== args.resourceId
+    ) {
+      throw new Error("Review comment not found");
+    }
+    const isAuthor =
+      Boolean(actionCtx?.userEmail) &&
+      normalizeEmail(comment.authorEmail) ===
+        normalizeEmail(actionCtx?.userEmail);
+    if (!isAuthor && (!access || !roleSatisfies(access.role, "editor"))) {
+      throw new ForbiddenError("Not allowed to delete this review comment");
+    }
+    const updatedCount = await deleteReviewComment(
+      comment.id,
+      actionCtx?.userEmail ?? null,
+    );
+    if (updatedCount < 1) {
+      throw new Error("Review comment not found");
+    }
+    return { commentId: comment.id, deleted: true as const, updatedCount };
+  },
+  audit: {
+    target: (args) => ({
+      type: args.resourceType,
+      id: args.resourceId,
+    }),
+  },
+});
+
+function normalizeEmail(email: string | null | undefined): string | null {
+  const normalized = email?.trim().toLowerCase();
+  return normalized || null;
+}

package/corpus/core/src/review/actions/get-review-feedback.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertReviewableResourceAccess } from "../registry.js";
+import { queryReviewComments } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  includeHumanTargeted: z.boolean().optional(),
+  limit: z.number().int().positive().max(500).optional(),
+});
+
+export default defineAction({
+  description:
+    "Get open review feedback that is ready for the agent to consider.",
+  schema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    const comments = await queryReviewComments({
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      scope: {
+        userEmail: actionCtx?.userEmail ?? null,
+        orgId: actionCtx?.orgId ?? null,
+      },
+      bypassScope: true,
+      includeResolved: false,
+      includeDeleted: false,
+      limit: args.limit,
+    });
+    return {
+      comments: comments.filter((comment) => {
+        if (comment.consumedAt) {
+          return false;
+        }
+        if (args.includeHumanTargeted) {
+          return true;
+        }
+        return comment.resolutionTarget !== "human";
+      }),
+    };
+  },
+});

package/corpus/core/src/review/actions/list-review-comments.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertReviewableResourceAccess } from "../registry.js";
+import { getReviewStatus, queryReviewComments } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  includeResolved: z.boolean().optional(),
+  includeDeleted: z.boolean().optional(),
+  targetId: z.string().nullable().optional(),
+  limit: z.number().int().positive().max(500).optional(),
+});
+
+export default defineAction({
+  description:
+    "List inline comments, annotations, and review threads for a resource.",
+  schema,
+  http: { method: "GET" },
+  readOnly: true,
+  parallelSafe: true,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const [comments, reviewStatus] = await Promise.all([
+      queryReviewComments({
+        resourceType: args.resourceType,
+        resourceId: args.resourceId,
+        scope,
+        bypassScope: true,
+        includeResolved: args.includeResolved,
+        includeDeleted: args.includeDeleted,
+        targetId: args.targetId,
+        limit: args.limit,
+      }),
+      getReviewStatus(args.resourceType, args.resourceId, scope, {
+        bypassScope: true,
+      }),
+    ]);
+    return { comments, reviewStatus };
+  },
+});

package/corpus/core/src/review/actions/reply-review-comment.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { extractReviewMentions, normalizeReviewMentions } from "../mentions.js";
+import {
+  assertReviewableResourceAccess,
+  normalizeReviewVisibility,
+} from "../registry.js";
+import { getReviewCommentById, insertReviewComment } from "../store.js";
+import type { ReviewActorKind, ReviewResourceContext } from "../types.js";
+
+const mentionSchema = z.object({
+  label: z.string().min(1),
+  email: z.string().email().nullable().optional(),
+  id: z.string().nullable().optional(),
+});
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  commentId: z.string().min(1),
+  body: z.string().min(1),
+  authorName: z.string().nullable().optional(),
+  resolutionTarget: z.enum(["agent", "human"]).nullable().optional(),
+  mentions: z.array(mentionSchema).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export default defineAction({
+  description: "Reply to an existing review comment thread.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const access = await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "viewer",
+    );
+    const parent = await getReviewCommentById(args.commentId, scope, {
+      bypassScope: true,
+    });
+    if (
+      !parent ||
+      parent.resourceType !== args.resourceType ||
+      parent.resourceId !== args.resourceId
+    ) {
+      throw new Error("Review comment not found");
+    }
+    const mentions = normalizeReviewMentions([
+      ...normalizeReviewMentions(args.mentions),
+      ...extractReviewMentions(args.body),
+    ]);
+
+    return insertReviewComment({
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      threadId: parent.threadId,
+      parentCommentId: parent.id,
+      targetId: parent.targetId,
+      kind: parent.kind,
+      anchor: parent.anchor,
+      body: args.body,
+      authorEmail: actionCtx?.userEmail ?? null,
+      authorName: args.authorName ?? actionCtx?.userEmail ?? null,
+      createdBy: actorKindFromContext(actionCtx),
+      resolutionTarget:
+        args.resolutionTarget ??
+        (mentions.length > 0 ? "human" : parent.resolutionTarget),
+      mentions,
+      ownerEmail: access.ownerEmail ?? actionCtx?.userEmail ?? null,
+      orgId: access.orgId ?? actionCtx?.orgId ?? null,
+      visibility: normalizeReviewVisibility(access.visibility),
+      metadata: args.metadata,
+    });
+  },
+  audit: {
+    target: (args, result) => {
+      const comment = result as {
+        ownerEmail?: string | null;
+        orgId?: string | null;
+        visibility?: "private" | "org" | "public";
+      };
+      return {
+        type: args.resourceType,
+        id: args.resourceId,
+        ownerEmail: comment.ownerEmail,
+        orgId: comment.orgId,
+        visibility: comment.visibility,
+      };
+    },
+  },
+});
+
+function actorKindFromContext(
+  ctx: ReviewResourceContext | undefined,
+): ReviewActorKind {
+  const caller = typeof ctx?.caller === "string" ? ctx.caller : "";
+  if (caller === "agent" || caller === "tool") {
+    return "agent";
+  }
+  return ctx?.userEmail ? "human" : "system";
+}

package/corpus/core/src/review/actions/resolve-review-thread.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { assertReviewableResourceAccess } from "../registry.js";
+import { getReviewCommentById, resolveReviewThread } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  threadId: z.string().optional(),
+  commentId: z.string().optional(),
+});
+
+export default defineAction({
+  description: "Resolve an inline comment or review thread.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "editor",
+    );
+    let threadId = args.threadId;
+    if (!threadId && args.commentId) {
+      const comment = await getReviewCommentById(
+        args.commentId,
+        {
+          userEmail: actionCtx?.userEmail ?? null,
+          orgId: actionCtx?.orgId ?? null,
+        },
+        { bypassScope: true },
+      );
+      if (
+        !comment ||
+        comment.resourceType !== args.resourceType ||
+        comment.resourceId !== args.resourceId
+      ) {
+        throw new Error("Review comment not found");
+      }
+      threadId = comment.threadId;
+    }
+    if (!threadId) {
+      throw new Error("Provide threadId or commentId");
+    }
+    const updatedCount = await resolveReviewThread(
+      threadId,
+      actionCtx?.userEmail ?? null,
+      {
+        resourceType: args.resourceType,
+        resourceId: args.resourceId,
+      },
+    );
+    if (updatedCount < 1) {
+      throw new Error("Review thread not found");
+    }
+    return { threadId, resolved: true as const, updatedCount };
+  },
+  audit: {
+    target: (args) => ({
+      type: args.resourceType,
+      id: args.resourceId,
+    }),
+  },
+});

package/corpus/core/src/review/actions/set-review-status.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import {
+  assertReviewableResourceAccess,
+  normalizeReviewVisibility,
+} from "../registry.js";
+import { upsertReviewStatus } from "../store.js";
+import type { ReviewResourceContext } from "../types.js";
+
+const schema = z.object({
+  resourceType: z.string().min(1),
+  resourceId: z.string().min(1),
+  status: z.enum(["draft", "in_review", "approved", "changes_requested"]),
+  note: z.string().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export default defineAction({
+  description: "Set the review status for a reusable resource.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as ReviewResourceContext | undefined;
+    const access = await assertReviewableResourceAccess(
+      args.resourceType,
+      args.resourceId,
+      actionCtx,
+      "editor",
+    );
+    return upsertReviewStatus({
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+      status: args.status,
+      note: args.note,
+      updatedBy: actionCtx?.userEmail ?? null,
+      ownerEmail: access.ownerEmail ?? actionCtx?.userEmail ?? null,
+      orgId: access.orgId ?? actionCtx?.orgId ?? null,
+      visibility: normalizeReviewVisibility(access.visibility),
+      metadata: args.metadata,
+    });
+  },
+  audit: {
+    target: (args, result) => {
+      const status = result as {
+        ownerEmail?: string | null;
+        orgId?: string | null;
+        visibility?: "private" | "org" | "public";
+      };
+      return {
+        type: args.resourceType,
+        id: args.resourceId,
+        ownerEmail: status.ownerEmail,
+        orgId: status.orgId,
+        visibility: status.visibility,
+      };
+    },
+  },
+});

package/corpus/core/src/review/index.ts

@@ -0,0 +1,31 @@
+export type {
+  ReviewActorKind,
+  ReviewComment,
+  ReviewCommentKind,
+  ReviewCommentStatus,
+  ReviewMention,
+  ReviewResolutionTarget,
+  ReviewResourceAccess,
+  ReviewResourceContext,
+  ReviewResourceRole,
+  ReviewScope,
+  ReviewStatus,
+  ReviewStatusEntry,
+  ReviewableResourceRegistration,
+} from "./types.js";
+export { extractReviewMentions, normalizeReviewMentions } from "./mentions.js";
+export {
+  __resetReviewableResourcesForTests,
+  assertReviewableResourceAccess,
+  getReviewableResource,
+  listReviewableResources,
+  registerReviewableResource,
+  resolveReviewableResourceAccess,
+} from "./registry.js";
+export {
+  __resetReviewInitForTests,
+  ensureReviewTables,
+  getReviewCommentById,
+  getReviewStatus,
+  queryReviewComments,
+} from "./store.js";

package/corpus/core/src/review/mentions.ts

@@ -0,0 +1,44 @@
+import type { ReviewMention } from "./types.js";
+
+const MAILTO_MENTION_PATTERN = /@\[([^\]]+)\]\(mailto:([^)]+)\)/g;
+
+export function extractReviewMentions(body: string): ReviewMention[] {
+  const mentions: ReviewMention[] = [];
+  for (const match of body.matchAll(MAILTO_MENTION_PATTERN)) {
+    const label = match[1]?.trim();
+    const email = match[2]?.trim().toLowerCase();
+    if (label && email) {
+      mentions.push({ label, email });
+    }
+  }
+  return normalizeReviewMentions(mentions);
+}
+
+export function normalizeReviewMentions(
+  mentions: ReviewMention[] | null | undefined,
+): ReviewMention[] {
+  if (!mentions?.length) {
+    return [];
+  }
+  const seen = new Set<string>();
+  const normalized: ReviewMention[] = [];
+  for (const mention of mentions) {
+    const label = mention.label?.trim();
+    const email = mention.email?.trim().toLowerCase() || null;
+    const id = mention.id?.trim() || null;
+    if (!label && !email && !id) {
+      continue;
+    }
+    const key = email ?? id ?? label.toLowerCase();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    normalized.push({
+      label: label || email || id || "Unknown",
+      email,
+      id,
+    });
+  }
+  return normalized;
+}