@agent-native/core 0.90.2 → 0.90.3

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

@@ -0,0 +1,170 @@
+import {
+  AGENT_NATIVE_OPEN_PATH,
+  withCollapsedAgentSidebarParam,
+} from "../shared/agent-sidebar-url.js";
+
+export const STANDARD_APP_ROUTES = {
+  home: "/",
+  settings: "/settings",
+  team: "/team",
+} as const;
+
+export const STANDARD_SETTINGS_TABS = {
+  general: "general",
+  agent: "agent",
+  providers: "providers",
+  connections: "connections",
+  secrets: "secrets",
+  team: "team",
+  usage: "usage",
+  language: "language",
+  whatsNew: "whats-new",
+} as const;
+
+export type StandardAppRouteId = keyof typeof STANDARD_APP_ROUTES;
+export type StandardSettingsTabId =
+  (typeof STANDARD_SETTINGS_TABS)[keyof typeof STANDARD_SETTINGS_TABS];
+
+export interface BuildStandardAppRouteOptions {
+  settingsTab?: StandardSettingsTabId | string | null;
+  teamInSettings?: boolean;
+}
+
+export interface BuildResourceRouteOptions {
+  basePath?: string;
+}
+
+export interface NavigationTarget {
+  app?: string;
+  view: string;
+  params?: Record<string, string | number | boolean | null | undefined>;
+  to?: string;
+}
+
+export interface NavigationLink extends NavigationTarget {
+  label: string;
+  url: string;
+}
+
+export type StandardOpenPathRoute =
+  | string
+  | ((params: Record<string, string>) => string | null | undefined);
+
+export interface StandardOpenPathResolverOptions {
+  fallback?: StandardOpenPathRoute;
+}
+
+function normalizeLeadingPath(path: string): string {
+  const trimmed = path.trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return `/${trimmed.replace(/^\/+/, "").replace(/\/+$/, "")}`;
+}
+
+function normalizeTabId(tab: string): string {
+  return tab
+    .trim()
+    .replace(/^#/, "")
+    .toLowerCase()
+    .replace(/['"]/g, "")
+    .replace(/[\s_]+/g, "-");
+}
+
+function pathSegment(value: string): string {
+  return encodeURIComponent(value.trim().replace(/^\/+|\/+$/g, ""));
+}
+
+function resolveOpenPathRoute(
+  route: StandardOpenPathRoute | undefined,
+  params: Record<string, string>,
+): string | null | undefined {
+  if (!route) return null;
+  return typeof route === "function" ? route(params) : route;
+}
+
+export function buildSettingsRoute(
+  tab?: StandardSettingsTabId | string | null,
+  basePath = STANDARD_APP_ROUTES.settings,
+): string {
+  const path = normalizeLeadingPath(basePath);
+  const normalizedTab = tab ? normalizeTabId(tab) : null;
+  if (!normalizedTab || normalizedTab === STANDARD_SETTINGS_TABS.general) {
+    return path;
+  }
+  return `${path}#${encodeURIComponent(normalizedTab)}`;
+}
+
+export function buildTeamRoute(
+  options: Pick<BuildStandardAppRouteOptions, "teamInSettings"> = {},
+): string {
+  return options.teamInSettings
+    ? buildSettingsRoute(STANDARD_SETTINGS_TABS.team)
+    : STANDARD_APP_ROUTES.team;
+}
+
+export function buildStandardAppRoute(
+  route: StandardAppRouteId,
+  options: BuildStandardAppRouteOptions = {},
+): string {
+  if (route === "settings") return buildSettingsRoute(options.settingsTab);
+  if (route === "team") return buildTeamRoute(options);
+  return STANDARD_APP_ROUTES[route];
+}
+
+export function buildResourceRoute(
+  collection: string,
+  resourceId: string,
+  options: BuildResourceRouteOptions = {},
+): string {
+  const base = normalizeLeadingPath(options.basePath ?? "/");
+  const collectionPath = collection
+    .split("/")
+    .map((segment) => pathSegment(segment))
+    .filter(Boolean)
+    .join("/");
+  if (!collectionPath) throw new Error("collection is required");
+  if (!resourceId.trim()) throw new Error("resourceId is required");
+  const prefix = base === "/" ? "" : base;
+  return `${prefix}/${collectionPath}/${pathSegment(resourceId)}`;
+}
+
+export function buildOpenRoutePath(input: NavigationTarget): string {
+  const sp = new URLSearchParams();
+  if (input.app) sp.set("app", input.app);
+  sp.set("view", input.view);
+  if (input.to) sp.set("to", input.to);
+  for (const [key, value] of Object.entries(input.params ?? {})) {
+    if (value === undefined || value === null || value === "") continue;
+    sp.set(key, String(value));
+  }
+  return withCollapsedAgentSidebarParam(`${AGENT_NATIVE_OPEN_PATH}?${sp}`);
+}
+
+export function buildOpenRouteLink(
+  input: NavigationTarget & { label?: string },
+): NavigationLink {
+  return {
+    ...input,
+    label: input.label ?? `Open ${input.view}`,
+    url: buildOpenRoutePath(input),
+  };
+}
+
+export function createStandardOpenPathResolver(
+  routes: Record<string, StandardOpenPathRoute>,
+  options: StandardOpenPathResolverOptions = {},
+) {
+  return (input: {
+    app?: string;
+    view?: string;
+    params: Record<string, string>;
+  }): string | null | undefined => {
+    void input.app;
+    if (!input.view)
+      return resolveOpenPathRoute(options.fallback, input.params);
+    return (
+      resolveOpenPathRoute(routes[input.view], input.params) ??
+      resolveOpenPathRoute(options.fallback, input.params) ??
+      `/${input.view}`
+    );
+  };
+}

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

@@ -10,6 +10,14 @@ export type {
   OrgPendingInvitation,
 } from "./types.js";
 
+export {
+  canInviteOrgMembers,
+  canManageOrg,
+  canManageOrgDomain,
+  orgRoleAtLeast,
+  orgRoleRank,
+} from "./permissions.js";
+
 export {
   getOrgContext,
   getOrgDomain,

package/corpus/core/src/org/permissions.ts

@@ -0,0 +1,30 @@
+import type { OrgRole } from "./types.js";
+
+const ORG_ROLE_RANK: Record<OrgRole, number> = {
+  member: 1,
+  admin: 2,
+  owner: 3,
+};
+
+export function orgRoleRank(role: OrgRole | null | undefined): number {
+  return role ? (ORG_ROLE_RANK[role] ?? 0) : 0;
+}
+
+export function orgRoleAtLeast(
+  role: OrgRole | null | undefined,
+  minimum: OrgRole,
+): boolean {
+  return orgRoleRank(role) >= orgRoleRank(minimum);
+}
+
+export function canManageOrg(role: OrgRole | null | undefined): boolean {
+  return orgRoleAtLeast(role, "admin");
+}
+
+export function canInviteOrgMembers(role: OrgRole | null | undefined): boolean {
+  return orgRoleAtLeast(role, "admin");
+}
+
+export function canManageOrgDomain(role: OrgRole | null | undefined): boolean {
+  return role === "owner";
+}

package/corpus/core/src/org-team/index.ts

@@ -0,0 +1 @@
+export * from "../org/index.js";

package/corpus/core/src/private-blob/registry.ts

@@ -125,6 +125,7 @@ async function putViaEncryptedPublicUpload(
     filename: input.filename ?? input.key ?? "private-blob.bin",
     mimeType: "application/octet-stream",
     ownerEmail: input.ownerEmail,
+    recordAsset: false,
   });
   if (!uploaded) return null;
 

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

@@ -0,0 +1,38 @@
+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",
+    );
+    await consumeReviewFeedback(args.commentIds, undefined, {
+      resourceType: args.resourceType,
+      resourceId: args.resourceId,
+    });
+    return { consumedCommentIds: args.commentIds };
+  },
+  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,55 @@
+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) &&
+      comment.authorEmail === actionCtx?.userEmail;
+    if (!isAuthor && (!access || !roleSatisfies(access.role, "editor"))) {
+      throw new ForbiddenError("Not allowed to delete this review comment");
+    }
+    await deleteReviewComment(comment.id, actionCtx?.userEmail ?? null);
+    return { commentId: comment.id, deleted: true };
+  },
+  audit: {
+    target: (args) => ({
+      type: args.resourceType,
+      id: args.resourceId,
+    }),
+  },
+});

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";
+}