@agent-native/core 0.162.0 → 0.163.0

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

package/dist/sharing/schema.d.ts

@@ -42,7 +42,7 @@ export declare function ownableColumns(): {
  * Columns:
  * - `id`              — share row id (generated by the share action)
  * - `resourceId`      — id of the parent resource
- * - `principalType`   — `'user' | 'org'`
+ * - `principalType`   — `'user' | 'group' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
  * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
@@ -100,14 +100,14 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "org" | "user";
+            data: "group" | "org" | "user";
             driverParam: string;
             notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["user", "org"];
+            enumValues: ["user", "group", "org"];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -195,7 +195,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
 }>;
 export type Visibility = "private" | "org" | "public";
 export type ShareRole = "viewer" | "commenter" | "editor" | "admin";
-export type PrincipalType = "user" | "org";
+export type PrincipalType = "user" | "group" | "org";
 /** Role precedence — higher number = stronger capability. */
 export declare const ROLE_RANK: Record<ShareRole | "owner", number>;
 export declare function roleSatisfies(actual: ShareRole | "owner", minimum: ShareRole | "owner"): boolean;

package/dist/sharing/schema.js

@@ -49,7 +49,7 @@ export function ownableColumns() {
  * Columns:
  * - `id`              — share row id (generated by the share action)
  * - `resourceId`      — id of the parent resource
- * - `principalType`   — `'user' | 'org'`
+ * - `principalType`   — `'user' | 'group' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
  * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
@@ -65,7 +65,7 @@ export function createSharesTable(tableName) {
         id: text("id").primaryKey(),
         resourceId: text("resource_id").notNull(),
         principalType: text("principal_type", {
-            enum: ["user", "org"],
+            enum: ["user", "group", "org"],
         }).notNull(),
         principalId: text("principal_id").notNull(),
         role: text("role", {

package/dist/templates/chat/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/dist/templates/default/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/dist/templates/workspace-core/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/dist/workspace-connections/actions/list-workspace-user-groups.d.ts

@@ -1,2 +1,10 @@
-declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, import("../groups.js").WorkspaceUserGroup[]>;
+declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, {
+    id: string;
+    orgId: string;
+    name: string;
+    createdByEmail: string;
+    createdAt: string;
+    updatedAt: string;
+    memberEmails: any[];
+}[]>;
 export default _default;

package/dist/workspace-connections/actions/list-workspace-user-groups.js

@@ -1,13 +1,18 @@
 import { z } from "zod";
 import { defineAction } from "../../action.js";
-import { assertWorkspaceUserGroupManager, listWorkspaceUserGroupsForOrg, } from "../groups.js";
+import { listWorkspaceUserGroupsForOrg, workspaceUserGroupRole, } from "../groups.js";
 export default defineAction({
-    description: "List reusable workspace user groups. Group management is restricted to workspace owners and admins.",
+    description: "List reusable workspace user groups. Workspace members can see group names for sharing; only owners and admins receive member details and can manage groups.",
     schema: z.object({}),
     http: { method: "GET" },
     readOnly: true,
     run: async (_args, ctx) => {
-        await assertWorkspaceUserGroupManager(ctx?.orgId, ctx?.userEmail);
-        return listWorkspaceUserGroupsForOrg(ctx?.orgId ?? "");
+        const role = await workspaceUserGroupRole(ctx?.orgId, ctx?.userEmail);
+        if (!role)
+            throw new Error("Workspace membership is required.");
+        const groups = await listWorkspaceUserGroupsForOrg(ctx?.orgId ?? "");
+        if (role === "owner" || role === "admin")
+            return groups;
+        return groups.map((group) => ({ ...group, memberEmails: [] }));
     },
 });

package/dist/workspace-connections/groups.d.ts

@@ -20,12 +20,14 @@ export interface UpdateWorkspaceUserGroupMembersInput {
     operation: "add" | "remove";
     orgId?: string | null;
 }
+export declare function workspaceUserGroupsTable(): string;
 export declare function normalizeWorkspaceUserGroupIds(value: unknown): string[];
 export declare function ensureWorkspaceUserGroupsTable(): Promise<void>;
 export declare function listWorkspaceUserGroupsForOrg(orgId: string, groupIds?: string[]): Promise<WorkspaceUserGroup[]>;
 export declare function listWorkspaceUserGroups(): Promise<WorkspaceUserGroup[]>;
 export declare function assertWorkspaceUserGroupIds(groupIds: string[] | undefined, orgId: string | null | undefined): Promise<string[] | undefined>;
 export declare function assertWorkspaceUserGroupManager(orgId: string | null | undefined, userEmail: string | undefined): Promise<void>;
+export declare function workspaceUserGroupRole(orgId: string | null | undefined, userEmail: string | undefined): Promise<"owner" | "admin" | "member" | null>;
 export declare function upsertWorkspaceUserGroup(input: UpsertWorkspaceUserGroupInput): Promise<WorkspaceUserGroup>;
 export declare function updateWorkspaceUserGroupMembers(input: UpdateWorkspaceUserGroupMembersInput): Promise<WorkspaceUserGroup>;
 export declare function deleteWorkspaceUserGroup(id: string, orgId?: string | null): Promise<boolean>;

package/dist/workspace-connections/groups.js

@@ -3,7 +3,7 @@ import { getDbExec, intType, isPostgres, retryOnDdlRace, safeJsonParse, } from "
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { isOrgMember } from "../org/membership.js";
 import { getRequestOrgId, getRequestUserEmail, } from "../server/request-context.js";
-function workspaceUserGroupsTable() {
+export function workspaceUserGroupsTable() {
     return isPostgres()
         ? "public.workspace_user_groups"
         : "workspace_user_groups";
@@ -171,19 +171,25 @@ export async function assertWorkspaceUserGroupIds(groupIds, orgId) {
     return normalized;
 }
 export async function assertWorkspaceUserGroupManager(orgId, userEmail) {
+    const role = await workspaceUserGroupRole(orgId, userEmail);
+    if (role === "owner" || role === "admin")
+        return;
+    throw new Error("Only workspace admins can manage user groups.");
+}
+export async function workspaceUserGroupRole(orgId, userEmail) {
     const normalizedOrgId = orgId?.trim();
     const normalizedEmail = userEmail?.trim().toLowerCase();
     if (!normalizedOrgId || !normalizedEmail) {
-        throw new Error("Only workspace admins can manage user groups.");
+        return null;
     }
     const { rows } = await getDbExec().execute({
         sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
         args: [normalizedOrgId, normalizedEmail],
     });
     const role = String(rows[0]?.role ?? "");
-    if (role !== "owner" && role !== "admin") {
-        throw new Error("Only workspace admins can manage user groups.");
-    }
+    return role === "owner" || role === "admin" || role === "member"
+        ? role
+        : null;
 }
 export async function upsertWorkspaceUserGroup(input) {
     const requestScope = requireWorkspaceUserGroupScope();
@@ -283,6 +289,11 @@ export async function workspaceUserGroupsIncludeUser(orgId, groupIds, userEmail)
     if (!normalizedOrgId || !normalizedEmail || normalizedIds.length === 0) {
         return false;
     }
+    // Group rows can outlive roster membership. A stale email in the JSON
+    // member list must not keep granting access after that person leaves the
+    // organization.
+    if (!(await isOrgMember(normalizedOrgId, normalizedEmail)))
+        return false;
     const groups = await listWorkspaceUserGroupsForOrg(normalizedOrgId, normalizedIds);
     return groups.some((group) => group.memberEmails.includes(normalizedEmail));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.162.0",
+  "version": "0.163.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/templates/chat/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/src/templates/default/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |