@agent-native/core 0.162.0 → 0.163.1

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/auth.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { defineEventHandler, getMethod, getQuery, getRequestIP, setResponseHeader, setResponseStatus, getCookie, setCookie, deleteCookie, getHeader, } from "h3";
 import { getAppConfig } from "../app-config/index.js";
+import { isWorkspaceAppAccessAllowed } from "../org/workspace-app-access.js";
 import { EMBED_START_PATH } from "../shared/embed-auth.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_MAX_AGE, } from "../shared/first-run-onboarding.js";
@@ -2170,8 +2171,20 @@ function createAuthGuardFn(app) {
             return;
         }
         const session = await getSession(event);
-        if (session)
+        if (session) {
+            const workspaceAppId = getAppConfig().app.workspaceId?.trim() || "";
+            if (workspaceAppId &&
+                workspaceAppId !== "dispatch" &&
+                (p.startsWith("/api/") || p.startsWith("/_agent-native/")) &&
+                !(await isWorkspaceAppAccessAllowed(workspaceAppId, {
+                    email: session.email,
+                    orgId: session.orgId,
+                }))) {
+                setResponseStatus(event, 403);
+                return { error: "You do not have access to this workspace app." };
+            }
             return;
+        }
         if (p.startsWith("/api/") || p.startsWith("/_agent-native/")) {
             setResponseStatus(event, 401);
             return { error: "Unauthorized" };

package/dist/server/collab-plugin.d.ts

@@ -41,6 +41,8 @@ export interface CollabPluginOptions {
     idColumn?: string;
     /** Whether to auto-seed existing documents on startup. Default: true */
     autoSeed?: boolean;
+    /** Map a source-table id to the id used by the collab document store. */
+    resolveCollabDocumentId?: (sourceId: string) => string;
     /**
      * Callback invoked after a collab update to sync the content column.
      * If not provided, the plugin auto-syncs using table/contentColumn/idColumn.
@@ -78,4 +80,8 @@ export interface CollabPluginOptions {
 }
 export declare function normalizeCollabAccess(options: Pick<CollabPluginOptions, "access" | "resourceType" | "resolveResourceId">): NormalizedCollabAccess;
 export declare function createCollabPlugin(options?: CollabPluginOptions): NitroPluginDef;
+export declare function selectUnseededCollabRows(rows: ReadonlyArray<Record<string, unknown>>, idColumn: string, existingDocIds: ReadonlySet<string>, resolveCollabDocumentId?: (sourceId: string) => string): Array<{
+    row: Record<string, unknown>;
+    docId: string;
+}>;
 export {};

package/dist/server/collab-plugin.js

@@ -16,7 +16,7 @@ import { defineEventHandler, getMethod, setResponseStatus, } from "h3";
 import { postAwareness, getActiveUsers } from "../collab/awareness.js";
 import { getCollabEmitter } from "../collab/emitter.js";
 import { getCollabState, postCollabUpdate, postCollabText, postCollabSearchReplace, } from "../collab/routes.js";
-import { hasCollabState } from "../collab/storage.js";
+import { listCollabDocIds } from "../collab/storage.js";
 import { postCollabJson, getCollabJson, postCollabPatch, } from "../collab/struct-routes.js";
 import { seedFromText, seedFromJson } from "../collab/ydoc-manager.js";
 import { getDbExec } from "../db/client.js";
@@ -82,6 +82,7 @@ function warnForImplicitAllAuthenticatedAccess(table) {
 export function createCollabPlugin(options = {}) {
     const normalizedAccess = normalizeCollabAccess(options);
     const { table = "documents", contentColumn = "content", idColumn = "id", autoSeed = true, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, } = options;
+    const resolveCollabDocumentId = options.resolveCollabDocumentId ?? ((sourceId) => sourceId);
     const resourceType = normalizedAccess.mode === "resource"
         ? normalizedAccess.resourceType
         : undefined;
@@ -308,13 +309,14 @@ export function createCollabPlugin(options = {}) {
             // Run in background so it doesn't block startup
             setTimeout(async () => {
                 try {
+                    // Read existing ids once, then apply the plugin's document-id
+                    // mapping before filtering. A source-table SQL predicate can use
+                    // the wrong id for integrations such as Analytics' dash-* docs.
+                    const existingDocIds = await listCollabDocIds();
                     const client = getDbExec();
                     const { rows } = await client.execute(`SELECT ${idColumn}, ${seedColumn} FROM ${table}`);
-                    for (const row of rows) {
-                        const docId = row[idColumn];
-                        const exists = await hasCollabState(docId);
-                        if (exists)
-                            continue;
+                    for (const { row, docId } of selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId)) {
+                        let seeded = false;
                         if (isJson) {
                             const raw = row[seedColumn] ?? "{}";
                             try {
@@ -323,6 +325,7 @@ export function createCollabPlugin(options = {}) {
                                     ? "array"
                                     : "map";
                                 await seedFromJson(docId, parsed, "data", inferredType);
+                                seeded = true;
                             }
                             catch {
                                 // Invalid JSON — skip
@@ -331,7 +334,10 @@ export function createCollabPlugin(options = {}) {
                         else {
                             const content = row[seedColumn] ?? "";
                             await seedFromText(docId, content);
+                            seeded = true;
                         }
+                        if (seeded)
+                            existingDocIds.add(docId);
                     }
                 }
                 catch {
@@ -341,3 +347,18 @@ export function createCollabPlugin(options = {}) {
         }
     };
 }
+export function selectUnseededCollabRows(rows, idColumn, existingDocIds, resolveCollabDocumentId = (sourceId) => sourceId) {
+    const seenDocIds = new Set(existingDocIds);
+    const unseeded = [];
+    for (const row of rows) {
+        const sourceId = String(row[idColumn] ?? "");
+        if (!sourceId)
+            continue;
+        const docId = resolveCollabDocumentId(sourceId);
+        if (seenDocIds.has(docId))
+            continue;
+        seenDocIds.add(docId);
+        unseeded.push({ row, docId });
+    }
+    return unseeded;
+}

package/dist/server/deploy-environment.d.ts

@@ -5,7 +5,7 @@
  * not the vendor, and a second backend that reports errors without them
  * produces issues nobody can tie to a release.
  */
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export declare function resolveDeployEnvironment(): string;
 /**
  * Resolve the agent-native version baked into core's package.json so the

package/dist/server/deploy-environment.js

@@ -8,6 +8,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isAgentNativeDeploymentEnvironment } from "../config.js";
 function firstNonEmpty(...values) {
     for (const value of values) {
         const trimmed = value?.trim();
@@ -16,9 +17,46 @@ function firstNonEmpty(...values) {
     }
     return undefined;
 }
-/** The deploy environment name, e.g. `production`, `deploy-preview`. */
+function normalizeFallbackEnvironment(value) {
+    const normalized = firstNonEmpty(value)?.toLowerCase();
+    if (normalized === "development" || normalized === "test")
+        return "local";
+    return isAgentNativeDeploymentEnvironment(normalized)
+        ? normalized
+        : undefined;
+}
+/** The deploy environment name, e.g. `production`, `beta`, or `preview`. */
 export function resolveDeployEnvironment() {
-    return (firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NETLIFY_CONTEXT, process.env.VERCEL_ENV, process.env.NODE_ENV) ?? "production");
+    const explicit = firstNonEmpty(process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT)?.toLowerCase();
+    if (explicit) {
+        if (!isAgentNativeDeploymentEnvironment(explicit)) {
+            throw new Error('AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT must be "local", "beta", "production", or "preview"');
+        }
+        return explicit;
+    }
+    const context = firstNonEmpty(process.env.CONTEXT, process.env.NETLIFY_CONTEXT, process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT)?.toLowerCase();
+    const branch = process.env.BRANCH?.trim().toLowerCase();
+    const vercelEnv = process.env.VERCEL_ENV?.trim().toLowerCase();
+    if (branch === "beta")
+        return "beta";
+    if (branch === "production" ||
+        (context === "production" && branch !== "beta")) {
+        return "production";
+    }
+    if (context === "branch-deploy" && branch === "main")
+        return "beta";
+    if (context === "deploy-preview" ||
+        context === "branch-deploy" ||
+        branch?.startsWith("deploy-preview") ||
+        vercelEnv === "preview") {
+        return "preview";
+    }
+    if (!context && !branch && !vercelEnv) {
+        return (normalizeFallbackEnvironment(firstNonEmpty(process.env.SENTRY_ENVIRONMENT, process.env.NODE_ENV)) ?? "production");
+    }
+    return (normalizeFallbackEnvironment(firstNonEmpty(context, vercelEnv)) ??
+        normalizeFallbackEnvironment(process.env.NODE_ENV) ??
+        "production");
 }
 /**
  * Resolve the agent-native version baked into core's package.json so the

package/dist/server/poll.js

@@ -231,6 +231,12 @@ function extensionTargetsForRow(row, shareRows) {
         else if (principalType === "org" && principalId) {
             addExtensionTarget(targets, { orgId: principalId });
         }
+        else if (principalType === "group" && orgId) {
+            // Group membership is org-scoped. Invalidating the org target is a
+            // conservative fallback that keeps group-share changes fresh for every
+            // member without making the poll layer own group-directory queries.
+            addExtensionTarget(targets, { orgId });
+        }
     }
     return Array.from(targets.values());
 }

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/sentry-config.js

@@ -28,11 +28,15 @@ export function resolvePublicSentryDsn() {
 }
 export function getSentryClientConfigScript() {
     const dsn = resolvePublicSentryDsn();
-    if (!dsn)
-        return null;
+    const deploymentEnvironment = resolveDeployEnvironment();
     const config = {
-        sentryDsn: dsn,
-        sentryEnvironment: resolveSentryEnvironment(),
+        ...(dsn
+            ? {
+                sentryDsn: dsn,
+                sentryEnvironment: resolveSentryEnvironment(),
+            }
+            : {}),
+        deploymentEnvironment,
     };
     return [
         "<script data-agent-native-sentry-config>",

package/dist/server/sentry.js

@@ -62,6 +62,10 @@ export function initServerSentry() {
         // cookies, or process.env contents to Sentry without explicit consent.
         sendDefaultPii: false,
         beforeSend(event) {
+            event.tags = {
+                ...event.tags,
+                deployment_environment: resolveDeployEnvironment(),
+            };
             // Drop rules live in `error-noise-filter.ts` so every backend applies
             // the same ones — they describe which server errors are non-bugs in
             // this framework, not a Sentry preference.

package/dist/sharing/access.d.ts

@@ -5,8 +5,8 @@
  * 1. Direct ownership — `owner_email = currentUser`.
  * 2. Visibility — `'private' | 'org' | 'public'`. `org` grants read to anyone
  *    in the same org; `public` grants read to any authenticated user.
- * 3. Share rows — per-user or per-org grants in the `{type}_shares` table
- *    with a role (`viewer | commenter | editor | admin`).
+ * 3. Share rows — per-user, per-group, or per-org grants in the
+ *    `{type}_shares` table with a role (`viewer | commenter | editor | admin`).
  *
  * Use `applyAccessFilter()` on list/read queries to filter rows the current
  * user can see. Use `assertAccess()` at the top of write actions to reject

package/dist/sharing/access.js

@@ -5,16 +5,18 @@
  * 1. Direct ownership — `owner_email = currentUser`.
  * 2. Visibility — `'private' | 'org' | 'public'`. `org` grants read to anyone
  *    in the same org; `public` grants read to any authenticated user.
- * 3. Share rows — per-user or per-org grants in the `{type}_shares` table
- *    with a role (`viewer | commenter | editor | admin`).
+ * 3. Share rows — per-user, per-group, or per-org grants in the
+ *    `{type}_shares` table with a role (`viewer | commenter | editor | admin`).
  *
  * Use `applyAccessFilter()` on list/read queries to filter rows the current
  * user can see. Use `assertAccess()` at the top of write actions to reject
  * callers who lack the required role.
  */
 import { and, eq, or, sql } from "drizzle-orm";
+import { isPostgres } from "../db/client.js";
 import { orgMembers } from "../org/schema.js";
 import { getRequestAuthCapability, getRequestUserEmail, getRequestOrgId, } from "../server/request-context.js";
+import { workspaceUserGroupsIncludeUser, workspaceUserGroupsTable, } from "../workspace-connections/groups.js";
 import { listShareableResources, requireShareableResource, } from "./registry.js";
 import { ROLE_RANK } from "./schema.js";
 /**
@@ -140,6 +142,38 @@ export function accessFilter(resourceTable, sharesTable, rawCtx = currentAccess(
                     and ${shareScope}
                     and ${minRoleSql(minRole)})`);
     }
+    if (reg?.supportsGroupShares && normalizedUserEmail && orgId) {
+        const groupTable = sql.raw(workspaceUserGroupsTable());
+        const groupMemberPredicate = isPostgres()
+            ? sql `exists (
+          select 1
+          from jsonb_array_elements_text(
+            workspace_group.member_emails_json::jsonb
+          ) as group_member(email)
+          where lower(group_member.email) = ${normalizedUserEmail}
+        )`
+            : sql `exists (
+          select 1
+          from json_each(workspace_group.member_emails_json) as group_member
+          where lower(group_member.value) = ${normalizedUserEmail}
+        )`;
+        clauses.push(sql `exists (select 1 from ${sharesTable}
+                  where ${sharesTable.resourceId} = ${resourceTable.id}
+                    and ${sharesTable.principalType} = 'group'
+                    and ${minRoleSql(minRole)}
+                    and exists (
+                      select 1 from ${groupTable} as workspace_group
+                      where workspace_group.id = ${sharesTable.principalId}
+                        and workspace_group.org_id = ${resourceTable.orgId}
+                        and workspace_group.org_id = ${orgId}
+                        and exists (
+                          select 1 from ${orgMembers} as workspace_member
+                          where workspace_member.org_id = workspace_group.org_id
+                            and lower(workspace_member.email) = ${normalizedUserEmail}
+                        )
+                        and ${groupMemberPredicate}
+                    ))`);
+    }
     return or(...clauses) ?? sql `1=0`;
 }
 function ownerScopeFilter(reg, resourceTable, ctx) {
@@ -314,6 +348,9 @@ async function resolveAccessImpl(resourceType, resourceId, rawCtx = currentAcces
         ownerMatchesActiveScope(reg, resource, ctx)) {
         return { role: "owner", resource };
     }
+    if (reg.canManageAccess && (await reg.canManageAccess(resource, ctx))) {
+        return { role: "admin", resource };
+    }
     if (resource.visibility === "public" && reg.allowPublic !== false) {
         // No share row needed; default viewer unless the resource registration
         // deliberately grants a stronger public-by-link role or explicit shares
@@ -359,12 +396,28 @@ async function highestShareRole(reg, resourceId, ctx, resource) {
     if (orgId) {
         principalClauses.push(and(eq(reg.sharesTable.principalType, "org"), eq(reg.sharesTable.principalId, orgId)));
     }
+    let best = null;
+    if (reg.supportsGroupShares && normalizedUserEmail && resource.orgId) {
+        const groupRows = await db
+            .select({
+            principalId: reg.sharesTable.principalId,
+            role: reg.sharesTable.role,
+        })
+            .from(reg.sharesTable)
+            .where(and(eq(reg.sharesTable.resourceId, resourceId), eq(reg.sharesTable.principalType, "group")));
+        for (const row of groupRows) {
+            if (await workspaceUserGroupsIncludeUser(resource.orgId, [row.principalId], normalizedUserEmail)) {
+                if (!best || ROLE_RANK[row.role] > ROLE_RANK[best]) {
+                    best = row.role;
+                }
+            }
+        }
+    }
     const rows = await db
         .select({ role: reg.sharesTable.role })
         .from(reg.sharesTable)
         .where(and(eq(reg.sharesTable.resourceId, resourceId), or(...principalClauses)))
         .limit(10);
-    let best = null;
     for (const r of rows) {
         if (!best || ROLE_RANK[r.role] > ROLE_RANK[best])
             best = r.role;

package/dist/sharing/actions/list-resource-shares.d.ts

@@ -8,6 +8,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     policy: {
         allowPublic: boolean;
         requireOrgMemberForUserShares: boolean;
+        supportsGroupShares?: boolean;
     };
     orgId?: undefined;
     role?: undefined;
@@ -22,6 +23,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     policy: {
         allowPublic: boolean;
         requireOrgMemberForUserShares: boolean;
+        supportsGroupShares?: boolean;
     };
 }>;
 export default _default;

package/dist/sharing/actions/list-resource-shares.js

@@ -2,6 +2,7 @@ import { eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 import { defineAction } from "../../action.js";
 import { organizations } from "../../org/schema.js";
+import { listWorkspaceUserGroupsForOrg } from "../../workspace-connections/groups.js";
 import { resolveAccess } from "../access.js";
 import { requireShareableResource } from "../registry.js";
 async function loadOrgDisplayNames(db, shares) {
@@ -28,6 +29,24 @@ async function loadOrgDisplayNames(db, shares) {
         return new Map();
     }
 }
+async function loadGroupDisplayNames(orgId, shares) {
+    const groupIds = Array.from(new Set(shares
+        .filter((share) => share.principalType === "group" && share.principalId)
+        .map((share) => share.principalId)));
+    if (!groupIds.length || !orgId)
+        return new Map();
+    try {
+        const groups = await listWorkspaceUserGroupsForOrg(orgId, groupIds);
+        return new Map(groups.flatMap((group) => {
+            const id = group.id;
+            const name = group.name.trim();
+            return id && name ? [[id, name]] : [];
+        }));
+    }
+    catch {
+        return new Map();
+    }
+}
 export default defineAction({
     description: "List the current visibility and share grants on a shareable resource. Any read access is sufficient.",
     schema: z.object({
@@ -42,6 +61,9 @@ export default defineAction({
             // resources that haven't opted into restrictions.
             allowPublic: reg.allowPublic !== false,
             requireOrgMemberForUserShares: reg.requireOrgMemberForUserShares === true,
+            ...(reg.supportsGroupShares === true
+                ? { supportsGroupShares: true }
+                : {}),
         };
         // Only `ownerEmail`/`orgId`/`visibility` are read below, all of which the
         // projected load carries — so the share dialog never pulls a resource's
@@ -55,6 +77,7 @@ export default defineAction({
             .from(reg.sharesTable)
             .where(eq(reg.sharesTable.resourceId, args.resourceId));
         const orgDisplayNames = await loadOrgDisplayNames(db, shares);
+        const groupDisplayNames = await loadGroupDisplayNames(access.resource.orgId, shares);
         return {
             ownerEmail: access.resource.ownerEmail ?? null,
             orgId: access.resource.orgId ?? null,
@@ -67,7 +90,9 @@ export default defineAction({
                 principalId: s.principalId,
                 displayName: s.principalType === "org"
                     ? orgDisplayNames.get(s.principalId)
-                    : undefined,
+                    : s.principalType === "group"
+                        ? groupDisplayNames.get(s.principalId)
+                        : undefined,
                 role: s.role,
                 createdAt: s.createdAt,
             })),

package/dist/sharing/actions/share-resource.d.ts

@@ -3,7 +3,7 @@ export declare function resolveShareNotificationUrl(explicitUrl: string | undefi
 declare const _default: import("../../action.js").ActionDefinition<{
     resourceType: string;
     resourceId: string;
-    principalType: "org" | "user";
+    principalType: "group" | "org" | "user";
     principalId: string;
     role?: "admin" | "commenter" | "editor" | "viewer";
     notify?: boolean;

package/dist/sharing/actions/share-resource.js

@@ -8,6 +8,7 @@ import { sendEmail, isEmailConfigured } from "../../server/email.js";
 import { invalidateCollabAccessCache } from "../../server/poll.js";
 import { getRequestUserEmail } from "../../server/request-context.js";
 import { getUserProfile } from "../../user-profile/store.js";
+import { assertWorkspaceUserGroupIds } from "../../workspace-connections/groups.js";
 import { assertAccess, ForbiddenError } from "../access.js";
 import { requireShareableResource } from "../registry.js";
 import { getExtensionShareChangeTargets, notifyExtensionShareChanged, } from "./extension-change.js";
@@ -122,7 +123,7 @@ async function isOrgMemberOrInvited(orgId, email) {
     return invited.rows.length > 0;
 }
 export default defineAction({
-    description: "Grant a user or org access to a shareable resource. Owner or admin role required.",
+    description: "Grant a user, group, or org access to a shareable resource. Owner or admin role required.",
     // (audit H5) Sharing-grant operations are admin-tier and let a caller
     // expand who can read/write a resource. Refuse from the tools iframe
     // bridge so a malicious shared tool can't silently re-share its
@@ -134,11 +135,11 @@ export default defineAction({
             .describe("Registered resource type, e.g. 'document', 'form'."),
         resourceId: z.string().describe("Id of the resource to share."),
         principalType: z
-            .enum(["user", "org"])
-            .describe("'user' for an individual, 'org' for a whole organization."),
+            .enum(["user", "group", "org"])
+            .describe("'user' for an individual, 'group' for an organization group, or 'org' for the whole organization."),
         principalId: z
             .string()
-            .describe("Email (user) or org id (org) of the principal."),
+            .describe("Email (user), group id (group), or org id (org) of the principal."),
         role: z
             .enum(["viewer", "commenter", "editor", "admin"])
             .default("viewer")
@@ -165,9 +166,24 @@ export default defineAction({
         if (!actor)
             throw new ForbiddenError("Not signed in");
         const principalId = normalizePrincipalId(args.principalType, args.principalId);
+        if (args.principalType === "group" && reg.supportsGroupShares !== true) {
+            throw new ForbiddenError(`${reg.displayName} does not support organization groups yet.`);
+        }
         if (args.principalType === "user" && !isEmailPrincipalId(principalId)) {
             throw new Error("User shares must use an email address, not an internal user id.");
         }
+        if (args.principalType === "group") {
+            const resourceOrgId = access.resource?.orgId;
+            if (!resourceOrgId) {
+                throw new ForbiddenError(`${reg.displayName} can only be shared with a group from within an organization.`);
+            }
+            try {
+                await assertWorkspaceUserGroupIds([principalId], resourceOrgId);
+            }
+            catch {
+                throw new ForbiddenError(`${reg.displayName} can only be shared with a group from its own organization.`);
+            }
+        }
         const beforeExtensionTargets = await getExtensionShareChangeTargets(args.resourceType, args.resourceId);
         if (reg.requireOrgMemberForUserShares) {
             const resourceOrgId = access.resource?.orgId;
@@ -189,6 +205,9 @@ export default defineAction({
                     throw new ForbiddenError(`${reg.displayName} can only be shared with its own organization, not a different one.`);
                 }
             }
+            else if (args.principalType === "group") {
+                // Group ownership was validated above against the resource org.
+            }
         }
         const db = reg.getDb();
         const [existing] = await db

package/dist/sharing/actions/unshare-resource.d.ts

@@ -1,7 +1,7 @@
 declare const _default: import("../../action.js").ActionDefinition<{
     resourceType: string;
     resourceId: string;
-    principalType: "org" | "user";
+    principalType: "group" | "org" | "user";
     principalId: string;
 }, {
     ok: boolean;

package/dist/sharing/actions/unshare-resource.js

@@ -22,7 +22,7 @@ export default defineAction({
     schema: z.object({
         resourceType: z.string(),
         resourceId: z.string(),
-        principalType: z.enum(["user", "org"]),
+        principalType: z.enum(["user", "group", "org"]),
         principalId: z.string(),
     }),
     run: async (args) => {

package/dist/sharing/registry.d.ts

@@ -168,6 +168,18 @@ export interface ShareableResourceRegistration {
      * Default: `false` (matches the historical behavior — any email can be granted).
      */
     requireOrgMemberForUserShares?: boolean;
+    /** Set true when this resource's DB is mounted with the org group tables. */
+    supportsGroupShares?: boolean;
+    /**
+     * Optional resource-specific manager check. Returning true grants the
+     * caller admin capability even when the row is private or they have no
+     * explicit share. Workspace apps use this for organization owners/admins;
+     * the owner is still recognized by the normal owner_email check.
+     */
+    canManageAccess?: (resource: any, ctx: {
+        userEmail?: string;
+        orgId?: string;
+    }) => boolean | Promise<boolean>;
     /**
      * Optional per-resource access-context adapter. Most resources should use the
      * request user/org unchanged. Templates with an intentional alternate local