@oxygen-agent/cli 1.1021.7 → 1.1022.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +1 -1
  2. package/dist/command-families/program.js +2 -0
  3. package/dist/command-families/tables/bundle-export.d.ts +2 -1
  4. package/dist/command-families/tables/bundle-export.js +14 -3
  5. package/dist/command-manifest.js +2 -0
  6. package/dist/command-support.d.ts +6 -0
  7. package/dist/command-support.js +61 -9
  8. package/dist/commands/agent.js +2 -2
  9. package/dist/commands/approvals.js +3 -52
  10. package/dist/commands/billing.js +5 -5
  11. package/dist/commands/context.js +2 -2
  12. package/dist/commands/copilot.js +1 -1
  13. package/dist/commands/knowledge.js +2 -2
  14. package/dist/commands/members.d.ts +7 -0
  15. package/dist/commands/members.js +32 -0
  16. package/dist/commands/orgs.js +1 -1
  17. package/dist/commands/publishing.js +36 -2
  18. package/dist/commands/recipes.js +1 -1
  19. package/dist/commands/sequences.js +4 -4
  20. package/dist/commands/suppressions.js +2 -2
  21. package/dist/commands/verify.js +1 -1
  22. package/dist/commands/workspace-export.d.ts +61 -0
  23. package/dist/commands/workspace-export.js +565 -0
  24. package/dist/commands/workspace.js +24 -1
  25. package/dist/help.js +6 -1
  26. package/node_modules/@oxygen/shared/dist/access/permissions.d.ts +101 -0
  27. package/node_modules/@oxygen/shared/dist/access/permissions.js +129 -0
  28. package/node_modules/@oxygen/shared/dist/access/roles.d.ts +73 -0
  29. package/node_modules/@oxygen/shared/dist/access/roles.js +116 -0
  30. package/node_modules/@oxygen/shared/dist/agents/sessions.js +2 -1
  31. package/node_modules/@oxygen/shared/dist/agents/teammates.js +2 -1
  32. package/node_modules/@oxygen/shared/dist/capability-intents/collaboration.js +7 -6
  33. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.d.ts +12 -0
  34. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.js +54 -0
  35. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.rules.d.ts +2 -0
  36. package/node_modules/@oxygen/shared/dist/capability-intents/discovery-and-skills.rules.js +19 -0
  37. package/node_modules/@oxygen/shared/dist/capability-intents/index.generated.js +2 -0
  38. package/node_modules/@oxygen/shared/dist/capability-routes/discovery-and-skills.js +4 -4
  39. package/node_modules/@oxygen/shared/dist/collab.d.ts +0 -29
  40. package/node_modules/@oxygen/shared/dist/collab.js +0 -32
  41. package/node_modules/@oxygen/shared/dist/contracts/browser-operations.js +2 -2
  42. package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js +4 -3
  43. package/node_modules/@oxygen/shared/dist/contracts/publishing-reads.js +1 -1
  44. package/node_modules/@oxygen/shared/dist/copilot/access.d.ts +1 -1
  45. package/node_modules/@oxygen/shared/dist/copilot/access.js +2 -1
  46. package/node_modules/@oxygen/shared/dist/decision-ledger.generated.js +11 -0
  47. package/node_modules/@oxygen/shared/dist/onboarding/guided-activation.js +3 -1
  48. package/node_modules/@oxygen/shared/dist/product-briefing-rules.js +2 -2
  49. package/node_modules/@oxygen/shared/dist/product-doctrine.js +1 -1
  50. package/node_modules/@oxygen/shared/dist/version.d.ts +1 -1
  51. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  52. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  53. package/node_modules/@oxygen/shared/dist/version.js +1 -1
  54. package/package.json +1 -1
@@ -0,0 +1,101 @@
1
+ export type PermissionDefinition = {
2
+ id: string;
3
+ /** Short, customer-facing name: a role's list of what it may do. */
4
+ label: string;
5
+ /** One customer-facing sentence on what the permission covers. */
6
+ description: string;
7
+ /**
8
+ * Held by admins only. Each admin-only permission is enforced in the route
9
+ * that owns the action (requirePermission), not by the central request check.
10
+ */
11
+ adminOnly?: true;
12
+ };
13
+ export declare const PERMISSIONS: readonly [{
14
+ readonly id: "self_service";
15
+ readonly label: "Your own account";
16
+ readonly description: "Sign in, switch workspaces, manage your own sessions and API keys (each key keeps your role), use skills, and reach feedback and support.";
17
+ }, {
18
+ readonly id: "workspace.read";
19
+ readonly label: "See the workspace";
20
+ readonly description: "Open every table, record, sequence, conversation, dashboard and run, and run read-only queries.";
21
+ }, {
22
+ readonly id: "collab.participate";
23
+ readonly label: "Comment and decide approvals";
24
+ readonly description: "Comment on work and decide the approvals assigned to you.";
25
+ }, {
26
+ readonly id: "dashboards.edit";
27
+ readonly label: "Build dashboards";
28
+ readonly description: "Create, change and share dashboards. A widget that spends credits also needs “Spend credits”.";
29
+ }, {
30
+ readonly id: "credits.spend";
31
+ readonly label: "Spend credits";
32
+ readonly description: "Run paid actions within the workspace budget and your own credit limit.";
33
+ }, {
34
+ readonly id: "copilot.use";
35
+ readonly label: "Work with Copilot and Oxygents";
36
+ readonly description: "Chat with the Copilot and Oxygents, on your own and in group chats.";
37
+ }, {
38
+ readonly id: "research.run";
39
+ readonly label: "Find people and companies";
40
+ readonly description: "Run people and company searches, and find emails and phone numbers.";
41
+ }, {
42
+ readonly id: "tables.work";
43
+ readonly label: "Edit rows and run enrichments";
44
+ readonly description: "Add and edit rows and run columns in existing tables. Creating tables or changing columns is “Build and set up”.";
45
+ }, {
46
+ readonly id: "crm.edit";
47
+ readonly label: "Work in the CRM";
48
+ readonly description: "Log activities, add notes, tasks, files and tags to records, and link records.";
49
+ }, {
50
+ readonly id: "messages.send";
51
+ readonly label: "Reply in the Unibox";
52
+ readonly description: "Reply to and triage conversations, and review drafted replies.";
53
+ }, {
54
+ readonly id: "sequences.enroll";
55
+ readonly label: "Add leads to sequences";
56
+ readonly description: "Add leads to sequences that are already built, and take them out again.";
57
+ }, {
58
+ readonly id: "senders.connect";
59
+ readonly label: "Connect your own sender";
60
+ readonly description: "Connect your own mailbox or LinkedIn account. Each connected account takes a paid seat.";
61
+ }, {
62
+ readonly id: "workspace.manage";
63
+ readonly label: "Build and set up";
64
+ readonly description: "Everything not listed separately: create tables and sequences, launch campaigns, build workflows and Oxygents, edit Knowledge, connect integrations and sending setup, buy credit top-ups.";
65
+ }, {
66
+ readonly id: "billing.manage";
67
+ readonly label: "Manage billing";
68
+ readonly description: "Change or confirm the plan, cancel or resume it, sending seats and the Billing Portal.";
69
+ readonly adminOnly: true;
70
+ }, {
71
+ readonly id: "members.manage";
72
+ readonly label: "Manage members and roles";
73
+ readonly description: "Invite members and change their roles.";
74
+ readonly adminOnly: true;
75
+ }, {
76
+ readonly id: "budgets.manage";
77
+ readonly label: "Set budgets and limits";
78
+ readonly description: "Workspace budgets, credit caps and provider rate limits.";
79
+ readonly adminOnly: true;
80
+ }, {
81
+ readonly id: "gates.manage";
82
+ readonly label: "Set approval gates";
83
+ readonly description: "Require an approval before a launch or a sign-off.";
84
+ readonly adminOnly: true;
85
+ }, {
86
+ readonly id: "workspace.admin";
87
+ readonly label: "Workspace administration";
88
+ readonly description: "Beta features, egress IPs, Google Workspace, the placement-test network, UGC programs and ending the workspace's infrastructure.";
89
+ readonly adminOnly: true;
90
+ }];
91
+ export type PermissionId = (typeof PERMISSIONS)[number]["id"];
92
+ /**
93
+ * What a mutating request needs when no permission's grants name it. Holding it
94
+ * is what "can change anything not listed separately" means, so only admins and
95
+ * members do, and a route nobody classified stays closed to every restricted
96
+ * role.
97
+ */
98
+ export declare const FALLBACK_PERMISSION = "workspace.manage";
99
+ export declare function permissionDefinition(id: PermissionId): PermissionDefinition;
100
+ export declare function isPermissionId(value: unknown): value is PermissionId;
101
+ export declare function isAdminOnlyPermission(id: PermissionId): boolean;
@@ -0,0 +1,129 @@
1
+ // Workspace permissions (ADR 0033): the one vocabulary that roles, enforcement
2
+ // and every surface (web, CLI, MCP, Copilot) share.
3
+ //
4
+ // A permission names something a person may do in a workspace. A role is a
5
+ // bundle of permissions (roles.ts). Which requests a permission opens for a
6
+ // restricted role lives beside the enforcement, in
7
+ // apps/web/src/lib/access/route-grants/, one module per permission.
8
+ //
9
+ // Adding a permission: one entry here, the roles that hold it in roles.ts, and,
10
+ // when a restricted role holds it, its route grants. Anything a restricted role
11
+ // is not granted stays refused, so a new permission can never widen a role by
12
+ // omission.
13
+ //
14
+ // Browser-safe on purpose: the members page renders these labels.
15
+ export const PERMISSIONS = [
16
+ {
17
+ id: "self_service",
18
+ label: "Your own account",
19
+ description: "Sign in, switch workspaces, manage your own sessions and API keys (each key keeps your role), use skills, and reach feedback and support.",
20
+ },
21
+ {
22
+ id: "workspace.read",
23
+ label: "See the workspace",
24
+ description: "Open every table, record, sequence, conversation, dashboard and run, and run read-only queries.",
25
+ },
26
+ {
27
+ id: "collab.participate",
28
+ label: "Comment and decide approvals",
29
+ description: "Comment on work and decide the approvals assigned to you.",
30
+ },
31
+ {
32
+ id: "dashboards.edit",
33
+ label: "Build dashboards",
34
+ description: "Create, change and share dashboards. A widget that spends credits also needs “Spend credits”.",
35
+ },
36
+ {
37
+ id: "credits.spend",
38
+ label: "Spend credits",
39
+ description: "Run paid actions within the workspace budget and your own credit limit.",
40
+ },
41
+ {
42
+ id: "copilot.use",
43
+ label: "Work with Copilot and Oxygents",
44
+ description: "Chat with the Copilot and Oxygents, on your own and in group chats.",
45
+ },
46
+ {
47
+ id: "research.run",
48
+ label: "Find people and companies",
49
+ description: "Run people and company searches, and find emails and phone numbers.",
50
+ },
51
+ {
52
+ id: "tables.work",
53
+ label: "Edit rows and run enrichments",
54
+ description: "Add and edit rows and run columns in existing tables. Creating tables or changing columns is “Build and set up”.",
55
+ },
56
+ {
57
+ id: "crm.edit",
58
+ label: "Work in the CRM",
59
+ description: "Log activities, add notes, tasks, files and tags to records, and link records.",
60
+ },
61
+ {
62
+ id: "messages.send",
63
+ label: "Reply in the Unibox",
64
+ description: "Reply to and triage conversations, and review drafted replies.",
65
+ },
66
+ {
67
+ id: "sequences.enroll",
68
+ label: "Add leads to sequences",
69
+ description: "Add leads to sequences that are already built, and take them out again.",
70
+ },
71
+ {
72
+ id: "senders.connect",
73
+ label: "Connect your own sender",
74
+ description: "Connect your own mailbox or LinkedIn account. Each connected account takes a paid seat.",
75
+ },
76
+ {
77
+ id: "workspace.manage",
78
+ label: "Build and set up",
79
+ description: "Everything not listed separately: create tables and sequences, launch campaigns, build workflows and Oxygents, edit Knowledge, connect integrations and sending setup, buy credit top-ups.",
80
+ },
81
+ {
82
+ id: "billing.manage",
83
+ label: "Manage billing",
84
+ description: "Change or confirm the plan, cancel or resume it, sending seats and the Billing Portal.",
85
+ adminOnly: true,
86
+ },
87
+ {
88
+ id: "members.manage",
89
+ label: "Manage members and roles",
90
+ description: "Invite members and change their roles.",
91
+ adminOnly: true,
92
+ },
93
+ {
94
+ id: "budgets.manage",
95
+ label: "Set budgets and limits",
96
+ description: "Workspace budgets, credit caps and provider rate limits.",
97
+ adminOnly: true,
98
+ },
99
+ {
100
+ id: "gates.manage",
101
+ label: "Set approval gates",
102
+ description: "Require an approval before a launch or a sign-off.",
103
+ adminOnly: true,
104
+ },
105
+ {
106
+ id: "workspace.admin",
107
+ label: "Workspace administration",
108
+ description: "Beta features, egress IPs, Google Workspace, the placement-test network, UGC programs and ending the workspace's infrastructure.",
109
+ adminOnly: true,
110
+ },
111
+ ];
112
+ /**
113
+ * What a mutating request needs when no permission's grants name it. Holding it
114
+ * is what "can change anything not listed separately" means, so only admins and
115
+ * members do, and a route nobody classified stays closed to every restricted
116
+ * role.
117
+ */
118
+ export const FALLBACK_PERMISSION = "workspace.manage";
119
+ const PERMISSION_BY_ID = new Map(PERMISSIONS.map((permission) => [permission.id, permission]));
120
+ export function permissionDefinition(id) {
121
+ // Total over PermissionId by construction; the cast only narrows Map.get.
122
+ return PERMISSION_BY_ID.get(id);
123
+ }
124
+ export function isPermissionId(value) {
125
+ return typeof value === "string" && PERMISSION_BY_ID.has(value);
126
+ }
127
+ export function isAdminOnlyPermission(id) {
128
+ return permissionDefinition(id).adminOnly === true;
129
+ }
@@ -0,0 +1,73 @@
1
+ import { type PermissionId } from "./permissions.js";
2
+ /** The overlay values a membership can store, most capable first. */
3
+ export declare const OXYGEN_ROLES: readonly ["rep", "viewer", "client"];
4
+ export type OxygenRole = (typeof OXYGEN_ROLES)[number];
5
+ export type WorkspaceRoleId = "admin" | "member" | OxygenRole;
6
+ export type WorkspaceRoleDefinition = {
7
+ id: WorkspaceRoleId;
8
+ label: string;
9
+ /** One customer-facing sentence: what this role is for. */
10
+ summary: string;
11
+ permissions: readonly PermissionId[];
12
+ };
13
+ export declare const WORKSPACE_ROLES: readonly [{
14
+ readonly id: "admin";
15
+ readonly label: "Admin";
16
+ readonly summary: "Everything, including members and roles, billing, budgets and approval gates.";
17
+ readonly permissions: readonly ("billing.manage" | "budgets.manage" | "collab.participate" | "copilot.use" | "credits.spend" | "crm.edit" | "dashboards.edit" | "gates.manage" | "members.manage" | "messages.send" | "research.run" | "self_service" | "senders.connect" | "sequences.enroll" | "tables.work" | "workspace.admin" | "workspace.manage" | "workspace.read")[];
18
+ }, {
19
+ readonly id: "member";
20
+ readonly label: "Member";
21
+ readonly summary: "Builds, sets up and runs the workspace, without member, billing, budget or approval-gate settings.";
22
+ readonly permissions: readonly ("billing.manage" | "budgets.manage" | "collab.participate" | "copilot.use" | "credits.spend" | "crm.edit" | "dashboards.edit" | "gates.manage" | "members.manage" | "messages.send" | "research.run" | "self_service" | "senders.connect" | "sequences.enroll" | "tables.work" | "workspace.admin" | "workspace.manage" | "workspace.read")[];
23
+ }, {
24
+ readonly id: "rep";
25
+ readonly label: "Sales rep";
26
+ readonly summary: "Works their pipeline: finds and enriches leads, works the CRM and Unibox, adds leads to sequences and uses Copilot and Oxygents. Doesn't build or set anything up.";
27
+ readonly permissions: readonly ["self_service", "workspace.read", "collab.participate", "dashboards.edit", "credits.spend", "copilot.use", "research.run", "tables.work", "crm.edit", "messages.send", "sequences.enroll", "senders.connect"];
28
+ }, {
29
+ readonly id: "viewer";
30
+ readonly label: "Viewer";
31
+ readonly summary: "Sees everything, comments, decides the approvals assigned to them and builds dashboards. Spends no credits.";
32
+ readonly permissions: readonly ["self_service", "workspace.read", "collab.participate", "dashboards.edit"];
33
+ }, {
34
+ readonly id: "client";
35
+ readonly label: "Client";
36
+ readonly summary: "An agency's client: sees everything, comments and decides the approvals assigned to them. Nothing else.";
37
+ readonly permissions: readonly ["self_service", "workspace.read", "collab.participate"];
38
+ }];
39
+ export declare function workspaceRoleDefinition(id: WorkspaceRoleId): WorkspaceRoleDefinition;
40
+ export declare function roleHasPermission(role: WorkspaceRoleId, permission: PermissionId): boolean;
41
+ export declare function isOxygenRole(value: unknown): value is OxygenRole;
42
+ /**
43
+ * The Clerk membership roles that carry admin authority. Both spellings: Clerk
44
+ * writes the `org:`-prefixed form, older rows carry the bare one.
45
+ */
46
+ export declare const WORKSPACE_ADMIN_ROLES: readonly ["admin", "owner", "org:admin", "org:owner"];
47
+ export declare function isWorkspaceAdminRole(role: string | null | undefined): boolean;
48
+ /**
49
+ * The role a membership acts with: its overlay when one is set, else its Clerk
50
+ * role. The overlay wins even over a Clerk admin role; granting one to an admin
51
+ * is refused, and the members route stays open to Clerk admins (see
52
+ * apps/web/src/lib/access/role-access.ts) so a stale overlay can always be
53
+ * cleared.
54
+ *
55
+ * A stored value outside OXYGEN_ROLES cannot occur while the CHECK constraint
56
+ * holds. If it ever does, the safe reading of a broken overlay is the most
57
+ * restricted role, never full access.
58
+ */
59
+ export declare function effectiveWorkspaceRole(membership: {
60
+ role: string | null | undefined;
61
+ oxygenRole: string | null | undefined;
62
+ }): WorkspaceRoleId;
63
+ /**
64
+ * For feature gates that know only the overlay: may this membership use a
65
+ * feature that every member may use? No overlay means a member or an admin,
66
+ * who hold every permission that is not admin-only. Some callers spell "no
67
+ * overlay" as the role itself (`COALESCE(oxygen_role, 'member')`), so `member`
68
+ * and `admin` read as those roles; any other unknown value reads as the most
69
+ * restricted role.
70
+ */
71
+ export declare function oxygenRoleAllows(oxygenRole: string | null | undefined, permission: PermissionId): boolean;
72
+ /** The overlay roles that lack a permission, for SQL that filters memberships. */
73
+ export declare function oxygenRolesWithout(permission: PermissionId): OxygenRole[];
@@ -0,0 +1,116 @@
1
+ // Workspace roles (ADR 0033): named bundles of permissions.
2
+ //
3
+ // Admin and member come from the Clerk membership role. The others are an
4
+ // OXYGEN-side overlay stored on the membership
5
+ // (`organization_memberships.oxygen_role`), pinned by a CHECK constraint that
6
+ // must list exactly OXYGEN_ROLES. NULL there means no overlay: the Clerk role
7
+ // decides.
8
+ //
9
+ // Adding a role: its id in OXYGEN_ROLES, a migration widening both CHECK
10
+ // constraints, and its definition below. Changing what a role may do is an
11
+ // edit to its permission list, nothing else.
12
+ import { PERMISSIONS, isAdminOnlyPermission } from "./permissions.js";
13
+ /** The overlay values a membership can store, most capable first. */
14
+ export const OXYGEN_ROLES = ["rep", "viewer", "client"];
15
+ const ALL_PERMISSIONS = PERMISSIONS.map((permission) => permission.id);
16
+ const MEMBER_PERMISSIONS = ALL_PERMISSIONS.filter((id) => !isAdminOnlyPermission(id));
17
+ const CLIENT_PERMISSIONS = ["self_service", "workspace.read", "collab.participate"];
18
+ const VIEWER_PERMISSIONS = [...CLIENT_PERMISSIONS, "dashboards.edit"];
19
+ const REP_PERMISSIONS = [
20
+ ...VIEWER_PERMISSIONS,
21
+ "credits.spend",
22
+ "copilot.use",
23
+ "research.run",
24
+ "tables.work",
25
+ "crm.edit",
26
+ "messages.send",
27
+ "sequences.enroll",
28
+ "senders.connect",
29
+ ];
30
+ export const WORKSPACE_ROLES = [
31
+ {
32
+ id: "admin",
33
+ label: "Admin",
34
+ summary: "Everything, including members and roles, billing, budgets and approval gates.",
35
+ permissions: ALL_PERMISSIONS,
36
+ },
37
+ {
38
+ id: "member",
39
+ label: "Member",
40
+ summary: "Builds, sets up and runs the workspace, without member, billing, budget or approval-gate settings.",
41
+ permissions: MEMBER_PERMISSIONS,
42
+ },
43
+ {
44
+ id: "rep",
45
+ label: "Sales rep",
46
+ summary: "Works their pipeline: finds and enriches leads, works the CRM and Unibox, adds leads to sequences and uses Copilot and Oxygents. Doesn't build or set anything up.",
47
+ permissions: REP_PERMISSIONS,
48
+ },
49
+ {
50
+ id: "viewer",
51
+ label: "Viewer",
52
+ summary: "Sees everything, comments, decides the approvals assigned to them and builds dashboards. Spends no credits.",
53
+ permissions: VIEWER_PERMISSIONS,
54
+ },
55
+ {
56
+ id: "client",
57
+ label: "Client",
58
+ summary: "An agency's client: sees everything, comments and decides the approvals assigned to them. Nothing else.",
59
+ permissions: CLIENT_PERMISSIONS,
60
+ },
61
+ ];
62
+ const ROLE_BY_ID = new Map(WORKSPACE_ROLES.map((role) => [role.id, role]));
63
+ export function workspaceRoleDefinition(id) {
64
+ // Total over WorkspaceRoleId by construction; the cast only narrows Map.get.
65
+ return ROLE_BY_ID.get(id);
66
+ }
67
+ export function roleHasPermission(role, permission) {
68
+ return workspaceRoleDefinition(role).permissions.includes(permission);
69
+ }
70
+ export function isOxygenRole(value) {
71
+ return typeof value === "string" && OXYGEN_ROLES.includes(value);
72
+ }
73
+ /**
74
+ * The Clerk membership roles that carry admin authority. Both spellings: Clerk
75
+ * writes the `org:`-prefixed form, older rows carry the bare one.
76
+ */
77
+ export const WORKSPACE_ADMIN_ROLES = ["admin", "owner", "org:admin", "org:owner"];
78
+ export function isWorkspaceAdminRole(role) {
79
+ return typeof role === "string" && WORKSPACE_ADMIN_ROLES.includes(role.toLowerCase());
80
+ }
81
+ /**
82
+ * The role a membership acts with: its overlay when one is set, else its Clerk
83
+ * role. The overlay wins even over a Clerk admin role; granting one to an admin
84
+ * is refused, and the members route stays open to Clerk admins (see
85
+ * apps/web/src/lib/access/role-access.ts) so a stale overlay can always be
86
+ * cleared.
87
+ *
88
+ * A stored value outside OXYGEN_ROLES cannot occur while the CHECK constraint
89
+ * holds. If it ever does, the safe reading of a broken overlay is the most
90
+ * restricted role, never full access.
91
+ */
92
+ export function effectiveWorkspaceRole(membership) {
93
+ const overlay = membership.oxygenRole ?? null;
94
+ if (overlay !== null)
95
+ return isOxygenRole(overlay) ? overlay : "client";
96
+ return isWorkspaceAdminRole(membership.role) ? "admin" : "member";
97
+ }
98
+ /**
99
+ * For feature gates that know only the overlay: may this membership use a
100
+ * feature that every member may use? No overlay means a member or an admin,
101
+ * who hold every permission that is not admin-only. Some callers spell "no
102
+ * overlay" as the role itself (`COALESCE(oxygen_role, 'member')`), so `member`
103
+ * and `admin` read as those roles; any other unknown value reads as the most
104
+ * restricted role.
105
+ */
106
+ export function oxygenRoleAllows(oxygenRole, permission) {
107
+ if (oxygenRole === null || oxygenRole === undefined)
108
+ return !isAdminOnlyPermission(permission);
109
+ if (oxygenRole === "member" || oxygenRole === "admin")
110
+ return roleHasPermission(oxygenRole, permission);
111
+ return roleHasPermission(isOxygenRole(oxygenRole) ? oxygenRole : "client", permission);
112
+ }
113
+ /** The overlay roles that lack a permission, for SQL that filters memberships. */
114
+ export function oxygenRolesWithout(permission) {
115
+ return OXYGEN_ROLES.filter((role) => !roleHasPermission(role, permission));
116
+ }
@@ -1,4 +1,5 @@
1
1
  import { agentsEnabled, agentsEnabledIn } from "../agents-enabled.js";
2
+ import { oxygenRoleAllows } from "../access/roles.js";
2
3
  import { guidedActivationEnabled } from "../onboarding/guided-activation.js";
3
4
  import { networkMiningEnabled } from "../signals/network-mining.js";
4
5
  import { validateContract } from "../contracts/schema.js";
@@ -34,7 +35,7 @@ export function agentSessionsEnabledIn(organizationId, env = process.env) {
34
35
  return agentSessionsEnabled(env) && agentsEnabledIn(organizationId, env);
35
36
  }
36
37
  export function agentSessionsAvailableTo(env, viewer) {
37
- if (!agentSessionsEnabledIn(viewer.organizationId, env) || !viewer.member || viewer.oxygenRole === "client")
38
+ if (!agentSessionsEnabledIn(viewer.organizationId, env) || !viewer.member || !oxygenRoleAllows(viewer.oxygenRole, "copilot.use"))
38
39
  return false;
39
40
  return agentSessionsAudience(env) === "all" || guidedActivationEnabled(env) || isStaffEmail(viewer.email, env);
40
41
  }
@@ -1,4 +1,5 @@
1
1
  import { agentsEnabled, agentsEnabledIn } from "../agents-enabled.js";
2
+ import { oxygenRoleAllows } from "../access/roles.js";
2
3
  import { guidedActivationEnabled } from "../onboarding/guided-activation.js";
3
4
  import { isStaffEmail } from "../staff.js";
4
5
  export function teammatesAudience(env = process.env) {
@@ -17,7 +18,7 @@ export function teammatesEnabledIn(organizationId, env = process.env) {
17
18
  return teammatesEnabled(env) && agentsEnabledIn(organizationId, env);
18
19
  }
19
20
  export function teammatesAvailableTo(env, viewer) {
20
- if (!teammatesEnabledIn(viewer.organizationId, env) || !viewer.member || viewer.oxygenRole === "client")
21
+ if (!teammatesEnabledIn(viewer.organizationId, env) || !viewer.member || !oxygenRoleAllows(viewer.oxygenRole, "copilot.use"))
21
22
  return false;
22
23
  return teammatesAudience(env) === "all" || guidedActivationEnabled(env) || isStaffEmail(viewer.email, env);
23
24
  }
@@ -1,15 +1,16 @@
1
1
  /** Recommendations point to the mounted native owners, without conferring their write authority. */
2
2
  export function collaborationRecommendation(query) {
3
- const memberRead = { tools: ["oxygen_workspace_members_list"], commands: ["approvals client list"],
3
+ const memberRead = { tools: ["oxygen_workspace_members_list"], commands: ["members list"],
4
4
  execution: "Read workspace member roles, Clerk profiles and pending invitations. This does not invite anyone or change access. Free.", posture: "read_only" };
5
5
  const member = /\b(members?|memberships?)\b/.test(query);
6
6
  const workspace = /\b(workspace|organization|org)\b/.test(query);
7
- const clientRole = /\bclient (?:role|access|login)\b/.test(query);
8
- const roleWrite = /\b(set|change|grant|clear|remove|revoke|restrict|promote|demote)\b/.test(query);
7
+ // The restricted roles (ADR 0033), by name or as "<name> role/access/login".
8
+ const clientRole = /\b(?:client|viewer|sales rep|rep) (?:role|access|login)\b/.test(query)
9
+ || /\b(?:a|the) (?:sales rep|viewer)\b/.test(query) && /\brole|member\b/.test(query);
10
+ const roleWrite = /\b(set|change|grant|give|make|clear|remove|revoke|restrict|promote|demote)\b/.test(query);
9
11
  if (clientRole && roleWrite && !/\b(crm|records?|contacts?|companies|api|oauth)\b/.test(query)) {
10
- const clear = /\b(clear|remove|revoke)\b/.test(query);
11
- return { tools: ["oxygen_members_client_role_set", ...memberRead.tools], commands: [clear ? "approvals client revoke" : "approvals client grant", ...memberRead.commands],
12
- execution: "An admin can set or clear the restricted client overlay; a pending invite is checked in Clerk. This sends no invitation and does not change the Clerk workspace role. Free.", posture: "workspace_write" };
12
+ return { tools: ["oxygen_members_role_set", ...memberRead.tools], commands: ["members role", ...memberRead.commands],
13
+ execution: "An admin sets a member's role: admin, member, sales rep, viewer or client; a pending invite is checked in Clerk. This sends no invitation. Free.", posture: "workspace_write" };
13
14
  }
14
15
  if (workspace && member && roleWrite && /\b(roles?|admin|administrator)\b/.test(query))
15
16
  return {
@@ -0,0 +1,12 @@
1
+ /**
2
+ * "Export my whole workspace", "back up everything in our workspace", "we are
3
+ * migrating to hubspot, export everything": one local copy of the workspace
4
+ * (`workspace export`, Plain T-366). Without this the "workspace" term routed
5
+ * the ask to workspace-access, whose sign-in commands answered it.
6
+ *
7
+ * Only explicit whole-workspace phrasings match, so asks about one area, one
8
+ * attribute or a target company keep their owners: "export everything in our
9
+ * crm", "export my workspace usage report", "export the full account list",
10
+ * "export everything for churned accounts".
11
+ */
12
+ export declare function isWorkspaceExportIntent(query: string): boolean;
@@ -0,0 +1,54 @@
1
+ const EXPORT_VERB = /\b(export\w*|back ?up\w*|download\w*|cop(y|ies)|dump\w*|archiv\w*|snapshot\w*|take out|extract\w*|data out)\b/;
2
+ // Bringing a backup or another tool's export in, and other workspaces' words
3
+ // (Google Workspace, a mailbox provider), are never this export.
4
+ // "so we can import it later" is still the export.
5
+ const INBOUND = /\b(import\w*(?! (it|them|this|that|later)\b)|restor\w*|upload\w*|into|google workspace|gmail|outlook)\b/;
6
+ // Pushing data to another tool is its sync or push, not a local copy.
7
+ const PUSH_TO_TOOL = /\b(export|send|push|sync|copy)\w*( \S+){0,3} to (hubspot|salesforce|pipedrive|attio|apollo|clay|smartlead|heyreach|instantly|lemlist)\b/;
8
+ // Each pattern names the user's OXYGEN workspace as a whole. "Account", "org",
9
+ // "everything" or "switching" alone are GTM words about target companies, and
10
+ // "workspace" followed by one attribute (usage, URL, map) is that attribute.
11
+ const PURPOSE = String.raw `( (with|including|for|before|so|as|and|because|since)\b.*)?$`;
12
+ const WHOLE_WORKSPACE = /\b(whole|entire|full|complete) (oxygen )?workspace\b(?!'s| (map|ids?|url|usage|api|keys?|audit|logs?|cli|credits?|plan|billing|members?|invites?|name|logo|slug|reports?)\b)|\b((my|our) (whole|entire|full|complete) oxygen account|(whole|entire|full|complete) oxygen (account|workspace))\b|\b(my|our) (whole|entire) (org|organi[sz]ation|account)\b(?! (chart|list|data|history|plan|research)\b)|\b(full|complete) (copy|backup|export|dump) of (my |our |the |this )?(oxygen )?workspace\b/;
13
+ const WORKSPACE_NOUN = /\bworkspace (export|backup|back up|copy|dump|snapshot)\b/;
14
+ const VERB_ON_WORKSPACE = new RegExp(String.raw `\b((export|back ?up|download|dump|snapshot)\w* (a |an )?(my |our |the |this )?(oxygen )?workspace|(backup|back up|export|snapshot|archive|dump) of (my |our |the |this )?(whole |entire |full )?(oxygen )?workspace)${PURPOSE}`);
15
+ const WORKSPACE_DATA = /\b(oxygen|workspace) data\b|\b(full|complete) data (export|backup)\b|\b(dump|copy|export|backup) of (all )?(of )?(my |our |the )?data\b(?! (on|about|for|from|in) )/;
16
+ const EVERYTHING_IN_WORKSPACE = /\b(everything|all (of )?(my |our |the )?data) ((we|i) (have|keep|store) )?(in|from|on) (my |our |the |this )?(oxygen( workspace| account)?|workspace)\b/;
17
+ const BACK_UP_OXYGEN = /\b(back ?up|export|download|dump)\w*( up)? (my |our |all of |all )?oxygen\b(?! (cli|api|mcp|plugin|app|skills?|account (id|usage))\b)/;
18
+ // "Export everything" with nothing narrowing it, optionally followed by why or when.
19
+ const BARE_EVERYTHING = /\b(export|back ?up|download|copy|dump|snapshot)\w*( up)? (everything|all (of )?(my |our |the )?data)( (before|because|since|so|as|now|please)\b.*)?$/;
20
+ const BARE_FULL_BACKUP = /^(please )?(get |make |do |run |take |create )?(me )?(a |an )?(full|complete) (backup|export|copy)( of (my |our |the )?(oxygen |workspace )?(data|account|workspace))?$/;
21
+ // Every table at once is the tables part of the same export.
22
+ const ALL_TABLES = /\b(export|back ?up|download)\w*( up)? (every table|all (of )?(my |our |the |this )?tables)( (at once|in one step|in one go|together))?$/;
23
+ // First person, so "accounts that are switching providers" stays a sourcing ask.
24
+ const LEAVING = /\b(exit plan\w*|leav(e|ing) oxygen|off oxygen|(we're|we are|i'm|i am) (leaving|migrating|switching|moving|churning|cancell?ing)|(before|when|once|as) (we|i) (cancel|leave|churn|switch|migrate)\w*)\b/;
25
+ const OBJECT_NOUN = /\b(tables?|rows?|columns?|cells?|workflows?|sequences?|campaigns?|pages?|dashboards?|lists?|records?|contacts?|leads?|people|compan(y|ies)|accounts?|deals?|pipeline|posts?|tags?|messages?|conversations?|inbox|unibox|folders?|views?|signals?|icp|wiki|knowledge|crm|agents?|oxygents?|copilot|ads)\b/;
26
+ /**
27
+ * "Export my whole workspace", "back up everything in our workspace", "we are
28
+ * migrating to hubspot, export everything": one local copy of the workspace
29
+ * (`workspace export`, Plain T-366). Without this the "workspace" term routed
30
+ * the ask to workspace-access, whose sign-in commands answered it.
31
+ *
32
+ * Only explicit whole-workspace phrasings match, so asks about one area, one
33
+ * attribute or a target company keep their owners: "export everything in our
34
+ * crm", "export my workspace usage report", "export the full account list",
35
+ * "export everything for churned accounts".
36
+ */
37
+ export function isWorkspaceExportIntent(query) {
38
+ if (!EXPORT_VERB.test(query) || INBOUND.test(query) || PUSH_TO_TOOL.test(query))
39
+ return false;
40
+ return WHOLE_WORKSPACE.test(query)
41
+ || WORKSPACE_NOUN.test(query)
42
+ || VERB_ON_WORKSPACE.test(query)
43
+ || WORKSPACE_DATA.test(query)
44
+ || EVERYTHING_IN_WORKSPACE.test(query)
45
+ || BARE_EVERYTHING.test(query)
46
+ || BARE_FULL_BACKUP.test(query)
47
+ || ALL_TABLES.test(query)
48
+ || BACK_UP_OXYGEN.test(query)
49
+ // Leaving OXYGEN with the speaker's own data: "we're cancelling, export all our tables
50
+ // and wiki". One other kind of object ("export all deals before we migrate") keeps its owner.
51
+ || (LEAVING.test(query)
52
+ && /\b(everything|whole|(my |our )data|workspace|all (of )?(my |our |the )?(data|tables))\b/.test(query)
53
+ && !OBJECT_NOUN.test(query.replace(/\b(tables?|wiki|knowledge)\b/g, "")));
54
+ }
@@ -0,0 +1,2 @@
1
+ import type { CapabilityIntentRules } from "../capability-discovery-types.js";
2
+ export declare const rules: CapabilityIntentRules;
@@ -0,0 +1,19 @@
1
+ import { isWorkspaceExportIntent } from "./discovery-and-skills.js";
2
+ export const rules = {
3
+ explicit: [
4
+ // Ahead of the primitive rules: a whole-workspace export names tables,
5
+ // knowledge and settings, which their own cards would each claim.
6
+ { order: 15, route: (query) => isWorkspaceExportIntent(query) ? "discovery-and-skills" : null },
7
+ ],
8
+ recommendations: [
9
+ {
10
+ order: 15,
11
+ // MCP has no one-step export: its per-object exports follow the CLI command.
12
+ recommend: (card, query) => card.id === "discovery-and-skills" && isWorkspaceExportIntent(query) ? {
13
+ tools: ["oxygen_workspace_map", "oxygen_table_export_csv", "oxygen_workflows_export"],
14
+ commands: ["workspace export", "workspace map", "tables export-bundle"],
15
+ exactCommand: "oxygen workspace export --output <new-folder> --json",
16
+ } : null,
17
+ },
18
+ ],
19
+ };
@@ -5,6 +5,7 @@ import { rules as collaborationRules } from "./collaboration.rules.js";
5
5
  import { rules as connectedIntegrationsRules } from "./connected-integrations.rules.js";
6
6
  import { rules as connectedLinkedinRules } from "./connected-linkedin.rules.js";
7
7
  import { rules as connectedWhatsappRules } from "./connected-whatsapp.rules.js";
8
+ import { rules as discoveryAndSkillsRules } from "./discovery-and-skills.rules.js";
8
9
  import { rules as geoRules } from "./geo.rules.js";
9
10
  import { rules as knowledgeGraphRules } from "./knowledge-graph.rules.js";
10
11
  import { rules as linkedinPublicResearchRules } from "./linkedin-public-research.rules.js";
@@ -40,6 +41,7 @@ export const CAPABILITY_INTENT_RULES = [
40
41
  connectedIntegrationsRules,
41
42
  connectedLinkedinRules,
42
43
  connectedWhatsappRules,
44
+ discoveryAndSkillsRules,
43
45
  geoRules,
44
46
  knowledgeGraphRules,
45
47
  linkedinPublicResearchRules,
@@ -4,12 +4,12 @@ export const route = {
4
4
  id: "discovery-and-skills",
5
5
  layer: "Control",
6
6
  primitive: null,
7
- owns: "Bounded capability, command, provider-operation, Recipe, and product-skill discovery, plus INSTANCE discovery — what this workspace actually holds — with exact hydration on demand.",
7
+ owns: "Bounded capability, command, provider-operation, Recipe, and product-skill discovery, plus INSTANCE discovery — what this workspace actually holds — with exact hydration on demand, and a full local copy of it.",
8
8
  notFor: "Executing GTM work or loading full manifests and schemas before a capability is selected.",
9
- execution: "Search by outcome, choose the owner, then hydrate one exact command, MCP schema, provider descriptor, or skill. For instance discovery, read the map and then the primitive that owns the row.",
9
+ execution: "Search by outcome, choose the owner, then hydrate one exact command, MCP schema, provider descriptor, or skill. For instance discovery, read the map and then the primitive that owns the row. For a backup or before leaving, `workspace export --output <new folder>` (CLI, read-only, 0 credits) writes every table, wiki page, workflow, sequence, dashboard, tag, folder, do-not-contact list and readable setting with a manifest.json, never credentials; MCP exports one object at a time.",
10
10
  posture: "read_only",
11
11
  gatewayTools: ["oxygen_capabilities_search", "oxygen_skills_get", "oxygen_tools_search", "oxygen_recipes_list", "oxygen_workspace_map"],
12
- gatewayCommands: ["capabilities search", "commands search", "skills search", "tools search", "recipes list", "workspace map"],
12
+ gatewayCommands: ["capabilities search", "commands search", "skills search", "tools search", "recipes list", "workspace map", "workspace export"],
13
13
  skills: ["oxygen-quickstart", "oxygen-gtm"],
14
14
  // `workspace` (the map) belongs here rather than beside `home`: capability
15
15
  // discovery answers what OXYGEN can do and instance discovery answers what THIS
@@ -17,6 +17,6 @@ export const route = {
17
17
  // thing on demand. `home` stayed on the onboarding card because the standup is a
18
18
  // first-run surface; the map is not.
19
19
  endpointSections: ["skills", "workspace"],
20
- intentTerms: ["discover", "discovery", "capability", "capabilities", "command", "commands", "skill", "skills", "which tool", "how do i", "what do i have", "what is in my workspace", "workspace map"],
20
+ intentTerms: ["discover", "discovery", "capability", "capabilities", "command", "commands", "skill", "skills", "which tool", "how do i", "what do i have", "what is in my workspace", "workspace map", "workspace export", "workspace backup"],
21
21
  },
22
22
  };