@oxygen-agent/cli 1.1022.48 → 1.1023.41

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 (33) hide show
  1. package/README.md +1 -1
  2. package/dist/command-families/tables/register-views.js +3 -3
  3. package/dist/commands/approvals.js +1 -1
  4. package/dist/commands/members.js +1 -1
  5. package/dist/commands/orgs.js +1 -1
  6. package/dist/commands/publishing.js +10 -10
  7. package/dist/commands/sequences.js +6 -0
  8. package/node_modules/@oxygen/shared/dist/access/roles.d.ts +21 -8
  9. package/node_modules/@oxygen/shared/dist/access/roles.js +53 -16
  10. package/node_modules/@oxygen/shared/dist/capability-routes/geo.js +1 -1
  11. package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js +1 -1
  12. package/node_modules/@oxygen/shared/dist/contracts/geo.js +4 -4
  13. package/node_modules/@oxygen/shared/dist/geo/geo.js +1 -1
  14. package/node_modules/@oxygen/shared/dist/publishing/limits.d.ts +7 -0
  15. package/node_modules/@oxygen/shared/dist/publishing/limits.js +7 -0
  16. package/node_modules/@oxygen/shared/dist/social-capabilities.js +5 -3
  17. package/node_modules/@oxygen/shared/dist/tables/column-output-fields.js +12 -0
  18. package/node_modules/@oxygen/shared/dist/version.d.ts +1 -1
  19. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  20. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  21. package/node_modules/@oxygen/shared/dist/version.js +1 -1
  22. package/node_modules/@oxygen/workflows/dist/graph/diff.d.ts +2 -0
  23. package/node_modules/@oxygen/workflows/dist/graph/diff.js +3 -0
  24. package/node_modules/@oxygen/workflows/dist/graph/index.d.ts +1 -0
  25. package/node_modules/@oxygen/workflows/dist/graph/index.js +1 -0
  26. package/node_modules/@oxygen/workflows/dist/graph/lint.js +44 -1
  27. package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.d.ts +62 -0
  28. package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.js +22 -0
  29. package/node_modules/@oxygen/workflows/dist/graph/output.d.ts +36 -0
  30. package/node_modules/@oxygen/workflows/dist/graph/output.js +111 -0
  31. package/node_modules/@oxygen/workflows/dist/graph/types.d.ts +19 -0
  32. package/node_modules/@oxygen/workflows/dist/graph/types.js +8 -0
  33. package/package.json +1 -1
package/README.md CHANGED
@@ -34,4 +34,4 @@ oxygen update
34
34
 
35
35
  For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
36
36
 
37
- Version: 1.1022.48
37
+ Version: 1.1023.41
@@ -13,7 +13,7 @@ export function registerViews({ tablesCommand, handleAsyncAction }) {
13
13
  const TABLE_VIEW_CONFIG_HELP = 'JSON view config, typed v2 shape: {"version":2,"groupBy":"<select column key>","filterTree":{...},"sorts":[{"columnKey":"...","direction":"asc|desc"}],"visibleColumns":["..."],"cardFields":["..."]}. '
14
14
  + 'groupBy is the kanban group-by column (--group-by sets it for you); a complete board config is \'{"version":2,"groupBy":"lifecycle_stage"}\'. Malformed v2 is rejected with invalid_view_config.';
15
15
  tablesCommand.addCommand(new Command("views")
16
- .description("Create and manage saved table views (grid / kanban configurations).")
16
+ .description("Create and manage saved table views (grid / kanban / calendar configurations).")
17
17
  .addCommand(new Command("list")
18
18
  .description("List a table's saved views.")
19
19
  .argument("<table>", "Table id or slug.")
@@ -29,7 +29,7 @@ export function registerViews({ tablesCommand, handleAsyncAction }) {
29
29
  .description("Create a saved view.")
30
30
  .argument("<table>", "Table id or slug.")
31
31
  .requiredOption("--name <name>", "View name.")
32
- .option("--view-type <type>", "table (grid) or kanban (board split into lanes by a select/status column). Defaults to table; --group-by implies kanban. A kanban created without --group-by is not refused: the board renders on the table's first groupable column and every read reports that fallback as effective_group_by plus a warning, so pin the column with --group-by.")
32
+ .option("--view-type <type>", "table (grid), kanban (board split into lanes by a select/status column) or calendar (month grid by a date column; set it with --config '{\"version\":2,\"dateField\":\"<column>\"}'). Defaults to table; --group-by implies kanban. A kanban created without --group-by is not refused: the board renders on the table's first groupable column and every read reports that fallback as effective_group_by plus a warning, so pin the column with --group-by.")
33
33
  .option("--group-by <column>", "Kanban: the editable select/status column key the board splits on, e.g. --group-by lifecycle_stage. Unknown or non-groupable keys are refused with the groupable candidates. The response's effective_group_by is the column the board actually uses.")
34
34
  .option("--config <json>", TABLE_VIEW_CONFIG_HELP)
35
35
  .option("--default", "Make this the table's default view.")
@@ -54,7 +54,7 @@ export function registerViews({ tablesCommand, handleAsyncAction }) {
54
54
  .argument("<table>", "Table id or slug.")
55
55
  .argument("<view>", "View id.")
56
56
  .option("--name <name>", "Rename the view.")
57
- .option("--view-type <type>", "table (grid) or kanban (board). A kanban whose config names no group column renders on the first groupable column; reads report that fallback as effective_group_by plus a warning.")
57
+ .option("--view-type <type>", "table (grid), kanban (board) or calendar (month grid by the config's dateField). A kanban whose config names no group column renders on the first groupable column; reads report that fallback as effective_group_by plus a warning.")
58
58
  .option("--group-by <column>", "Kanban: change the select/status column the board splits on; folds into the stored config and keeps the rest of it. Refused for a grid view unless --view-type kanban is passed with it.")
59
59
  .option("--config <json>", `${TABLE_VIEW_CONFIG_HELP} Replaces the stored config.`)
60
60
  .option("--default", "Make this the table's default view.")
@@ -461,7 +461,7 @@ export function registerApprovalsFamily(program, handleAsyncAction) {
461
461
  }), formatCollabWriteResult);
462
462
  }))
463
463
  .addCommand(new Command("list")
464
- .description("Every member of this workspace and what they may do — the workspace role plus the Oxygen client overlay — followed by anyone invited who has not joined yet, and what they will land as. Also names, per member, why a client grant on them would be refused. Same read the /collab/members page renders.")
464
+ .description("Every member of this workspace and the role they hold, followed by anyone invited who has not joined yet, and what they will land as. Also names, per member, why a client grant on them would be refused. Same read the /collab/members page renders.")
465
465
  .option("--json", "Print a JSON envelope.")
466
466
  .action(async (options) => {
467
467
  await handleCollabAction("approvals client list", options, () => requestOxygen("/api/cli/collab/members"), formatWorkspaceMembers);
@@ -19,7 +19,7 @@ export function registerMembersFamily(program, _handleAsyncAction) {
19
19
  await handleCollabAction("members list", options, () => requestOxygen("/api/cli/collab/members"), formatWorkspaceMembers);
20
20
  }))
21
21
  .addCommand(new Command("role")
22
- .description(`Set a member's role. ADMIN ONLY. ${ROLE_HELP} An invited address that has not joined yet takes any role but admin, applied the moment they accept. You cannot change your own role, and a workspace admin must be made a member before taking a restricted role.`)
22
+ .description(`Set a member's role, which Clerk holds, so it also shows in Clerk's members list. ADMIN ONLY. ${ROLE_HELP} An invited address that has not joined yet takes any role but admin, applied the moment they accept. You cannot change your own role.`)
23
23
  .argument("<email>", "The member's email, or a pending invitation's email.")
24
24
  .requiredOption("--role <role>", `One of ${WORKSPACE_ROLES.map((role) => role.id).join(", ")}.`)
25
25
  .option("--json", "Print a JSON envelope.")
@@ -224,7 +224,7 @@ export function registerOrgsFamily(program, handleAsyncAction) {
224
224
  }));
225
225
  }))
226
226
  .addCommand(new Command("member-role")
227
- .description("Move a member between the admin and member workspace roles. ADMIN ONLY. This is the one Clerk membership change Oxygen makes — inviting people is still done in workspace settings. `oxygen members role` sets every role, including sales rep, viewer and client.")
227
+ .description("Make a member an admin or a member. ADMIN ONLY. Roles are held in Clerk; inviting people is still done in workspace settings. `oxygen members role` sets every role, including sales rep, viewer and client.")
228
228
  .argument("<email>", "Workspace member's email.")
229
229
  .requiredOption("--role <role>", "admin or member.")
230
230
  .option("--json", "Print a JSON envelope.")
@@ -254,7 +254,7 @@ function buildPublishingPostUpdateBody(options) {
254
254
  return body;
255
255
  }
256
256
  /**
257
- * The LinkedIn video cover flags: a media id, a local file uploaded first, or
257
+ * The video cover flags (LinkedIn videos, Instagram Reels): a media id, a local file uploaded first, or
258
258
  * (update only) a clear. Sent as the top-level `video_thumbnail_media_asset_id`,
259
259
  * which the server merges into content, so the post's attachments are untouched.
260
260
  */
@@ -805,8 +805,8 @@ export function registerPublishingFamily(program, handleAsyncAction) {
805
805
  .option("--reply-settings <who>", "X: who can reply: everyone, following, mentioned, or subscribers.")
806
806
  .option("--alt-text <media_id=text>", "X: image or GIF description for screen readers (up to 1,000 characters). Repeatable.", collectRepeatable, [])
807
807
  .option("--photo-tag <username>", "X: tag an account in the first post's images (up to 10). Repeatable.", collectRepeatable, [])
808
- .option("--video-thumbnail <media_id>", "LinkedIn video cover: an uploaded JPEG or PNG media id (`publishing media upload`). Needs a video in media_asset_ids.")
809
- .option("--video-thumbnail-file <path>", "Upload a local JPEG or PNG and use it as the LinkedIn video cover.")
808
+ .option("--video-thumbnail <media_id>", "Video cover for a LinkedIn video or Instagram Reel: an uploaded media id (`publishing media upload`); JPEG or PNG on LinkedIn, a JPEG up to 8 MB on Instagram. Needs a video in media_asset_ids (first on Instagram).")
809
+ .option("--video-thumbnail-file <path>", "Upload a local image and use it as the video cover (JPEG or PNG on LinkedIn, JPEG on Instagram).")
810
810
  .option("--json", "Print a JSON envelope.")
811
811
  .action(async (options) => {
812
812
  await handleAsyncAction("publishing posts create", options, async () => requestOxygen("/api/cli/publishing/posts", {
@@ -815,7 +815,7 @@ export function registerPublishingFamily(program, handleAsyncAction) {
815
815
  }));
816
816
  }))
817
817
  .addCommand(new Command("get")
818
- .description("Get one scheduled post with the sender account it publishes from (id, name, profile URL), resolved media previews, its LinkedIn video cover, and attempt history. For an X post, publish_plan lists every post that will be sent, in order, with media, alt text, poll and reply settings (free); for a LinkedIn post that tags a company page, it shows the text sent, each company tag as its page id, once `publishing posts approve` has resolved the tags (before approval it is absent). Open web_url to preview the post as it will look on LinkedIn or X.")
818
+ .description("Get one scheduled post with the sender account it publishes from (id, name, profile URL), resolved media previews, its video cover, and attempt history. For an X post, publish_plan lists every post that will be sent, in order, with media, alt text, poll and reply settings (free); for a LinkedIn post that tags a company page, it shows the text sent, each company tag as its page id, once `publishing posts approve` has resolved the tags (before approval it is absent). Open web_url to preview the post as it will look on LinkedIn or X.")
819
819
  .argument("<post_id>", "Scheduled post id.")
820
820
  .option("--json", "Print a JSON envelope.")
821
821
  .action(async (postId, options) => {
@@ -846,9 +846,9 @@ export function registerPublishingFamily(program, handleAsyncAction) {
846
846
  .option("--alt-text <media_id=text>", "X: image or GIF description for screen readers (up to 1,000 characters). Repeatable.", collectRepeatable, [])
847
847
  .option("--photo-tag <username>", "X: tag an account in the first post's images (up to 10). Repeatable.", collectRepeatable, [])
848
848
  .option("--content-merge-json <json>", "Merge content keys; null removes a key, e.g. '{\"poll\":null}'. Arrays, including mention_previews, are replaced whole: carry every entry you want to keep.")
849
- .option("--video-thumbnail <media_id>", "Set the LinkedIn video cover to an uploaded JPEG or PNG media id (`publishing media upload`). The post needs a video attached.")
850
- .option("--video-thumbnail-file <path>", "Upload a local JPEG or PNG and set it as the LinkedIn video cover. To pick a frame from the video instead, open the post's web_url and use Cover.")
851
- .option("--clear-video-thumbnail", "Remove the LinkedIn video cover.")
849
+ .option("--video-thumbnail <media_id>", "Set the video cover of a LinkedIn video or Instagram Reel to an uploaded media id (`publishing media upload`); JPEG or PNG on LinkedIn, a JPEG up to 8 MB on Instagram. The post needs a video attached (first on Instagram).")
850
+ .option("--video-thumbnail-file <path>", "Upload a local image and set it as the video cover (JPEG or PNG on LinkedIn, JPEG on Instagram). To pick a frame from the video instead, open the post's web_url and use Cover.")
851
+ .option("--clear-video-thumbnail", "Remove the video cover.")
852
852
  .option("--confirm-not-published", "Only after you checked the account: the post OXYGEN could not confirm is NOT there. Unlocks a post that failed with publishing_effect_outcome_uncertain; if the post is live, do not use it or it publishes twice.")
853
853
  .option("--json", "Print a JSON envelope.")
854
854
  .action(async (postId, options) => {
@@ -1065,7 +1065,7 @@ export function registerPublishingFamily(program, handleAsyncAction) {
1065
1065
  .addCommand(new Command("media")
1066
1066
  .description("Manage Publishing media uploads.")
1067
1067
  .addCommand(new Command("upload")
1068
- .description("Upload a local image, video, or PDF in one step and print its media id. Attach it with --content-json '{\"media_asset_ids\":[...]}', or use a JPEG/PNG as a LinkedIn video cover with `publishing posts update --video-thumbnail`.")
1068
+ .description("Upload a local image, video, or PDF in one step and print its media id. Attach it with --content-json '{\"media_asset_ids\":[...]}', or use an image as a video cover (LinkedIn, Instagram Reels) with `publishing posts update --video-thumbnail`.")
1069
1069
  .argument("<path>", "Local file path.")
1070
1070
  .option("--content-type <type>", "MIME type when the file extension does not say it, such as video/mp4.")
1071
1071
  .option("--scheduled-post <post_id>", "Optional provenance association; it does not attach the file to the post.")
@@ -1214,9 +1214,9 @@ export function registerPublishingFamily(program, handleAsyncAction) {
1214
1214
  }));
1215
1215
  })))
1216
1216
  .addCommand(new Command("analytics")
1217
- .description("Stored LinkedIn and X engagement snapshots synced in the background. LinkedIn includes owned posts discovered from the provider; X includes only posts published through OXYGEN. Reading analytics makes no provider call and uses 0 credits. A snapshotted post completed a sync pass; use per-metric coverage to see which values were populated. Null is unknown, never zero. Read freshness and guidance for delayed refresh; an unconfirmed provider read can pause it. No manual provider retry is available.")
1217
+ .description("Stored LinkedIn and X engagement snapshots synced in the background. LinkedIn and X include owned posts discovered from the provider, including ones made directly on the network. Reading analytics makes no provider call and uses 0 credits. A snapshotted post completed a sync pass; use per-metric coverage to see which values were populated. Null is unknown, never zero. Read freshness and guidance for delayed refresh; an unconfirmed provider read can pause it. No manual provider retry is available.")
1218
1218
  .addCommand(new Command("summary")
1219
- .description("Workspace LinkedIn or X analytics. LinkedIn includes owned posts discovered from the provider; X currently includes posts published through OXYGEN. Uses each post's latest stored snapshot; snapshotted_posts (legacy measured_posts) counts sync passes, while coverage counts non-null values. Read-only: no provider call, 0 credits.")
1219
+ .description("Workspace LinkedIn or X analytics. Both include owned posts discovered from the provider, including ones made directly on the network. Uses each post's latest stored snapshot; snapshotted_posts (legacy measured_posts) counts sync passes, while coverage counts non-null values. Read-only: no provider call, 0 credits.")
1220
1220
  .option("--channel <channel>", "Channel to summarize: linkedin (default) or x.")
1221
1221
  .option("--range <range>", "Publication window: 7d, 30d (default), 90d, or 365d.")
1222
1222
  .option("--from <date>", "Custom inclusive UTC start date.")
@@ -1534,6 +1534,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
1534
1534
  .description("List saved HubSpot contact/company segments and readable identity fields available for a Sequence import. These no-bill definition reads change no members, DNC entries, rows, workflows, or enrollments.")
1535
1535
  .argument("<sequence>", "Sequence id or slug.")
1536
1536
  .option("--query <text>", "Optional case-insensitive words to match in the HubSpot list name.")
1537
+ .option("--connection <id>", "HubSpot connection id to read (one of the returned connections). Defaults to the workspace default.")
1537
1538
  .option("--json", "Print a JSON envelope.")
1538
1539
  .action(async (sequence, options) => {
1539
1540
  await handleAsyncAction("sequences hubspot-list-import lists", options, () => {
@@ -1541,12 +1542,16 @@ export function registerSequencesFamily(program, handleAsyncAction) {
1541
1542
  const query = readOption(options.query);
1542
1543
  if (query)
1543
1544
  params.set("query", query);
1545
+ const connection = readOption(options.connection);
1546
+ if (connection)
1547
+ params.set("connection_id", connection);
1544
1548
  return requestOxygen(`/api/cli/sequencer/hubspot-list-import?${params.toString()}`);
1545
1549
  });
1546
1550
  }))
1547
1551
  .addCommand(new Command("configure")
1548
1552
  .description("Preview or start a scheduled HubSpot-list import. Preview first; then pass its reviewed fingerprint with --live --approved. The complete DNC list is applied before leads are read or enrolled.")
1549
1553
  .argument("<sequence>", "Sequence id or slug.")
1554
+ .option("--connection <id>", "HubSpot connection id every sync cycle reads. Defaults to the workspace default.")
1550
1555
  .requiredOption("--lead-list <id>", "Exact HubSpot ILS contact-list id whose current members should be imported.")
1551
1556
  .requiredOption("--dnc-list <id>", "Different exact HubSpot ILS contact-list id synchronized additively into Oxygen DNC first.")
1552
1557
  .option("--company-dnc-list <id>", "Optional HubSpot company-list id synchronized as all-channel company DNC.")
@@ -1584,6 +1589,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
1584
1589
  method: "POST",
1585
1590
  body: {
1586
1591
  sequence,
1592
+ ...(readOption(options.connection) ? { connection_id: readOption(options.connection) } : {}),
1587
1593
  lead_list_id: options.leadList,
1588
1594
  dnc_list_id: options.dncList,
1589
1595
  ...(readOption(options.companyDncList) ? { company_dnc_list_id: readOption(options.companyDncList) } : {}),
@@ -44,17 +44,30 @@ export declare function isOxygenRole(value: unknown): value is OxygenRole;
44
44
  * writes the `org:`-prefixed form, older rows carry the bare one.
45
45
  */
46
46
  export declare const WORKSPACE_ADMIN_ROLES: readonly ["admin", "owner", "org:admin", "org:owner"];
47
+ /** The Clerk membership roles of a plain member, in the same two spellings. */
48
+ export declare const WORKSPACE_MEMBER_ROLES: readonly ["member", "org:member"];
47
49
  export declare function isWorkspaceAdminRole(role: string | null | undefined): boolean;
50
+ /** The Clerk organization role that carries a workspace role. */
51
+ export declare function clerkRoleKey(role: WorkspaceRoleId): `org:${WorkspaceRoleId}`;
48
52
  /**
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.
53
+ * The workspace role a Clerk membership role carries. No role at all reads as
54
+ * a member, as it always has. A role nobody mapped (a custom role created in
55
+ * Clerk without an entry here) reads as the most restricted role, never as a
56
+ * member.
57
+ */
58
+ export declare function workspaceRoleForClerkRole(clerkRole: string | null | undefined): WorkspaceRoleId;
59
+ /** The restricted role a Clerk membership role carries, or null for an admin or member. */
60
+ export declare function oxygenRoleForClerkRole(clerkRole: string | null | undefined): OxygenRole | null;
61
+ /**
62
+ * The role a membership acts with. A restricted role held in Clerk decides.
63
+ * Otherwise a restriction set directly on the membership does, even over a
64
+ * Clerk admin, and the members route stays open to Clerk admins (see
65
+ * apps/web/src/lib/access/role-access.ts) so it can always be lifted. Without
66
+ * either, the Clerk admin or member role decides.
54
67
  *
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.
68
+ * A stored `oxygen_role` outside OXYGEN_ROLES cannot occur while the CHECK
69
+ * constraint holds. If it ever does, the safe reading of a broken value is the
70
+ * most restricted role, never full access.
58
71
  */
59
72
  export declare function effectiveWorkspaceRole(membership: {
60
73
  role: string | null | undefined;
@@ -1,14 +1,20 @@
1
1
  // Workspace roles (ADR 0033): named bundles of permissions.
2
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.
3
+ // Clerk assigns them: every role is a Clerk organization role keyed
4
+ // `org:<id>` (clerkRoleKey), so a member's role shows, and can be changed, in
5
+ // Clerk as well as in OXYGEN. This file decides what each role may do.
6
+ //
7
+ // The membership mirror keeps Clerk's key in `organization_memberships.role`
8
+ // and the restricted role it carries in `oxygen_role`, which role gates and
9
+ // SQL filters read (apps/web/src/lib/auth/membership-role-mirror.ts). A CHECK
10
+ // constraint pins `oxygen_role` to OXYGEN_ROLES. It can also be set directly
11
+ // on an admin or member: grants from before Clerk held roles, and grants made
12
+ // while a Clerk instance lacks the restricted roles.
8
13
  //
9
14
  // 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.
15
+ // constraints, its definition below, and its Clerk role in each instance
16
+ // (apps/web/scripts/setup-clerk-workspace-roles.ts). Changing what a role may
17
+ // do is an edit to its permission list, nothing else.
12
18
  import { PERMISSIONS, isAdminOnlyPermission } from "./permissions.js";
13
19
  /** The overlay values a membership can store, most capable first. */
14
20
  export const OXYGEN_ROLES = ["rep", "viewer", "client"];
@@ -75,25 +81,56 @@ export function isOxygenRole(value) {
75
81
  * writes the `org:`-prefixed form, older rows carry the bare one.
76
82
  */
77
83
  export const WORKSPACE_ADMIN_ROLES = ["admin", "owner", "org:admin", "org:owner"];
84
+ /** The Clerk membership roles of a plain member, in the same two spellings. */
85
+ export const WORKSPACE_MEMBER_ROLES = ["member", "org:member"];
78
86
  export function isWorkspaceAdminRole(role) {
79
87
  return typeof role === "string" && WORKSPACE_ADMIN_ROLES.includes(role.toLowerCase());
80
88
  }
89
+ /** The Clerk organization role that carries a workspace role. */
90
+ export function clerkRoleKey(role) {
91
+ return `org:${role}`;
92
+ }
93
+ /**
94
+ * The workspace role a Clerk membership role carries. No role at all reads as
95
+ * a member, as it always has. A role nobody mapped (a custom role created in
96
+ * Clerk without an entry here) reads as the most restricted role, never as a
97
+ * member.
98
+ */
99
+ export function workspaceRoleForClerkRole(clerkRole) {
100
+ if (clerkRole === null || clerkRole === undefined)
101
+ return "member";
102
+ if (isWorkspaceAdminRole(clerkRole))
103
+ return "admin";
104
+ const normalized = clerkRole.toLowerCase();
105
+ if (WORKSPACE_MEMBER_ROLES.includes(normalized))
106
+ return "member";
107
+ const id = normalized.startsWith("org:") ? normalized.slice("org:".length) : normalized;
108
+ return isOxygenRole(id) ? id : "client";
109
+ }
110
+ /** The restricted role a Clerk membership role carries, or null for an admin or member. */
111
+ export function oxygenRoleForClerkRole(clerkRole) {
112
+ const role = workspaceRoleForClerkRole(clerkRole);
113
+ return isOxygenRole(role) ? role : null;
114
+ }
81
115
  /**
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.
116
+ * The role a membership acts with. A restricted role held in Clerk decides.
117
+ * Otherwise a restriction set directly on the membership does, even over a
118
+ * Clerk admin, and the members route stays open to Clerk admins (see
119
+ * apps/web/src/lib/access/role-access.ts) so it can always be lifted. Without
120
+ * either, the Clerk admin or member role decides.
87
121
  *
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.
122
+ * A stored `oxygen_role` outside OXYGEN_ROLES cannot occur while the CHECK
123
+ * constraint holds. If it ever does, the safe reading of a broken value is the
124
+ * most restricted role, never full access.
91
125
  */
92
126
  export function effectiveWorkspaceRole(membership) {
127
+ const clerkRole = workspaceRoleForClerkRole(membership.role);
128
+ if (isOxygenRole(clerkRole))
129
+ return clerkRole;
93
130
  const overlay = membership.oxygenRole ?? null;
94
131
  if (overlay !== null)
95
132
  return isOxygenRole(overlay) ? overlay : "client";
96
- return isWorkspaceAdminRole(membership.role) ? "admin" : "member";
133
+ return clerkRole;
97
134
  }
98
135
  /**
99
136
  * For feature gates that know only the overlay: may this membership use a
@@ -2,7 +2,7 @@ export const route = {
2
2
  order: 100,
3
3
  card: {
4
4
  id: "geo", layer: "Data", primitive: "geo", posture: "mixed",
5
- owns: "GEO / AEO AI-search tracking: buyer prompts, consumer answers, citations, competitive visibility, customer chat evidence and optimization experiments. Experimental staff/dev access.",
5
+ owns: "SEO / GEO AI-search tracking: buyer prompts, consumer answers, citations, competitive visibility, customer chat evidence and optimization experiments. Experimental staff/dev access.",
6
6
  notFor: "Direct model API benchmarks, automatic public edits, autonomous publishing or personalized chat attribution.",
7
7
  execution: "Staff in dev workspaces only. Preview consumer collection and cost, start within the $10 shared pilot cap, inspect answers and citations, then record reviewed changes and compare later samples. Reads never collect or spend.",
8
8
  gatewayTools: ["oxygen_geo_projects_list", "oxygen_geo_engines_list", "oxygen_geo_analytics_get", "oxygen_geo_runs_preview"],
@@ -56,7 +56,7 @@ export const CUSTOMER_OPERATIONS = [
56
56
  operation("comments.edit", "/api/cli/collab/comments/{comment_id}", "PATCH", "comments edit", "oxygen_comments_edit", "collaboration", "Edit your own internal workspace comment; records the edit time.", { body: text() }, ["body"], mcpOnly),
57
57
  operation("comments.delete", "/api/cli/collab/comments/{comment_id}", "DELETE", "comments delete", "oxygen_comments_delete", "collaboration", "Retract your own internal workspace comment while retaining its audit trail.", {}, [], mcpOnly),
58
58
  operation("approvals.cancel", "/api/cli/collab/requests/{request_id}/cancel", "POST", "approvals cancel", "oxygen_approvals_cancel", "collaboration", "Withdraw an approval request you created; grants no approval.", { note: text() }, [], mcpOnly),
59
- operation("members.role", "/api/cli/collab/members/role", "POST", "members role", "oxygen_members_role_set", "collaboration", "Set a member's workspace role: admin, member, rep (sales rep), viewer or client; null only clears a restricted role. Admin only; you cannot change your own role, and an admin becomes a member before taking a restricted role. Admin and member change in Clerk; may read pending Clerk invitations; sends no invitation. Free.", { email: text(), role: nullable(enumOf(["admin", "member", ...OXYGEN_ROLES])) }, ["email", "role"], { ...mcpOnly, annotations: { openWorldHint: true } }),
59
+ operation("members.role", "/api/cli/collab/members/role", "POST", "members role", "oxygen_members_role_set", "collaboration", "Set a member's workspace role, held in Clerk: admin, member, rep (sales rep), viewer or client; null lifts a restricted role. Admin only; you cannot change your own role. May read pending Clerk invitations; sends no invitation. Free.", { email: text(), role: nullable(enumOf(["admin", "member", ...OXYGEN_ROLES])) }, ["email", "role"], { ...mcpOnly, annotations: { openWorldHint: true } }),
60
60
  operation("members.workspace_role", "/api/cli/collab/members/workspace-role", "POST", "orgs member-role", "oxygen_members_workspace_role_set", "collaboration", "Change a member's workspace role in Clerk; admin only, with self-role and last-administrator protection. Free.", { email: text(), role: enumOf(["admin", "member"]) }, ["email", "role"], { ...mcpOnly, annotations: { openWorldHint: true } }),
61
61
  operation("copilot.sessions.list", "/api/cli/copilot/sessions", "GET", "copilot list", "oxygen_copilot_sessions_list", "agents", "List attended Copilot sessions in this workspace.", COPILOT_SESSIONS_LIST_CONTRACT.properties, [], mcpOnly),
62
62
  operation("copilot.history", "/api/cli/copilot/sessions/{session_id}/history", "GET", "copilot history", "oxygen_copilot_history", "agents", "Search past Oxygent chat messages and recorded app links, with source-turn URLs. Use chat.session_id from oxygents get/list. Results index recorded links, not Markdown-only links; their source turn may be a later update, not creation. Markdown remains searchable as message text.", { query: str({ maxLength: 200, description: "Literal substring in user and assistant messages; also filters recorded links. Omit to list recorded links only." }), offset: int({ minimum: 0, description: "Page offset, initially 0; continue with next_offset from the previous response." }), limit: int({ minimum: 1, maximum: 100, description: "Items per page (default 30)." }) }, []),
@@ -75,14 +75,14 @@ function operation(id, suffix, method, command, summary, fields = {}, required =
75
75
  };
76
76
  }
77
77
  export const GEO_OPERATIONS = [
78
- operation("projects.list", "/projects", "GET", "projects list", "List GEO / AEO AI-search tracking projects."),
79
- operation("projects.create", "/projects", "POST", "projects create", "Create a GEO / AEO brand tracking project, private to the selected workspace and its authorized staff in dev. This never publishes data.", project, ["name", "domains"]),
80
- operation("projects.get", "/projects/{project_id}", "GET", "projects get", "Read a GEO / AEO project and its tracking settings."),
78
+ operation("projects.list", "/projects", "GET", "projects list", "List SEO / GEO AI-search tracking projects."),
79
+ operation("projects.create", "/projects", "POST", "projects create", "Create a SEO / GEO brand tracking project, private to the selected workspace and its authorized staff in dev. This never publishes data.", project, ["name", "domains"]),
80
+ operation("projects.get", "/projects/{project_id}", "GET", "projects get", "Read a SEO / GEO project and its tracking settings."),
81
81
  operation("projects.update", "/projects/{project_id}", "PATCH", "projects update", "Change brand aliases, ICP, markets or tracking settings.", project),
82
82
  operation("context.get", "/context", "GET", "context get", "Read editable brand, ICP and offering context from workspace Knowledge."),
83
83
  operation("engines.list", "/engines", "GET", "engines list", "Inspect consumer answer-engine readiness, supported markets and collection cost."),
84
84
  operation("prompts.list", "/projects/{project_id}/prompts", "GET", "prompts list", "List tracked buyer prompts and research provenance.", { limit: filters.limit, cursor: filters.cursor }),
85
- operation("prompts.create", "/projects/{project_id}/prompts", "POST", "prompts add", "Add a reviewed buyer question to GEO / AEO tracking.", prompt, ["text"]),
85
+ operation("prompts.create", "/projects/{project_id}/prompts", "POST", "prompts add", "Add a reviewed buyer question to SEO / GEO tracking.", prompt, ["text"]),
86
86
  operation("prompts.update", "/projects/{project_id}/prompts/{document_id}", "PATCH", "prompts update", "Revise or pause one tracked buyer question.", prompt),
87
87
  operation("prompts.import", "/projects/{project_id}/prompts/import", "POST", "prompts import", "Import reviewed buyer prompts in one bounded batch.", {
88
88
  prompts: arr(obj(prompt, { required: ["text"] }), {
@@ -34,7 +34,7 @@ export function isGeoEnabled(env = process.env) {
34
34
  }
35
35
  export function assertGeoEnabled(env = process.env) {
36
36
  if (!isGeoEnabled(env))
37
- throw new OxygenError("geo_unavailable", "GEO / AEO is available to staff on dev while it is being tested.", { exitCode: 1 });
37
+ throw new OxygenError("geo_unavailable", "SEO / GEO is available to staff on dev while it is being tested.", { exitCode: 1 });
38
38
  }
39
39
  export function geoDomain(value) {
40
40
  try {
@@ -22,3 +22,10 @@ export declare const X_PREMIUM_MAX_CHARS = 25000;
22
22
  * specific error instead of a generic schema rejection.
23
23
  */
24
24
  export declare const PUBLISHING_CONTENT_MAX_CHARS = 25000;
25
+ /**
26
+ * Meta fetches an Instagram Reel's `cover_url` itself and takes a JPEG of at most
27
+ * 8 MB (decimal, the conservative reading). The post write, the editor's picker
28
+ * and the worker all hold a cover to it, so a cover Meta would refuse never
29
+ * reaches a publish.
30
+ */
31
+ export declare const INSTAGRAM_REEL_COVER_MAX_BYTES = 8000000;
@@ -22,3 +22,10 @@ export const X_PREMIUM_MAX_CHARS = 25_000;
22
22
  * specific error instead of a generic schema rejection.
23
23
  */
24
24
  export const PUBLISHING_CONTENT_MAX_CHARS = X_PREMIUM_MAX_CHARS;
25
+ /**
26
+ * Meta fetches an Instagram Reel's `cover_url` itself and takes a JPEG of at most
27
+ * 8 MB (decimal, the conservative reading). The post write, the editor's picker
28
+ * and the worker all hold a cover to it, so a cover Meta would refuse never
29
+ * reaches a publish.
30
+ */
31
+ export const INSTAGRAM_REEL_COVER_MAX_BYTES = 8_000_000;
@@ -86,11 +86,13 @@ const X_COMPOSIO_CAPABILITIES = {
86
86
  provider_rail: "composio",
87
87
  operations: {
88
88
  list_owned_posts: {
89
- status: "unavailable",
89
+ status: "limited",
90
90
  source: "provider",
91
- provider_operation: null,
91
+ // The daily account read pages the account's own timeline (reposts left
92
+ // out); each page carries every post's counters, refreshed for a week.
93
+ provider_operation: "TWITTER_GET_USER_POSTS",
92
94
  external_write: false,
93
- limitation: "oxygen_published_posts_only",
95
+ limitation: "recent_owned_posts_7_day_refresh",
94
96
  },
95
97
  read_post_metrics: {
96
98
  status: "limited",
@@ -342,6 +342,18 @@ function toolContract(definition, options) {
342
342
  const mode = readString(definition.mode) ?? "native";
343
343
  if (mode === "company_enrichment_waterfall")
344
344
  return waterfallContract(definition);
345
+ if (mode === "workflow") {
346
+ // The workflow's declared output, snapshotted when the column was bound.
347
+ const schema = isRecord(definition.outputSchema) ? definition.outputSchema : null;
348
+ if (!schema)
349
+ return EMPTY_CONTRACT;
350
+ return {
351
+ schema,
352
+ fields: collectJsonSchemaFields(schema).map((raw) => toField(raw, "tool_schema")),
353
+ primaryField: null,
354
+ serverManaged: true,
355
+ };
356
+ }
345
357
  if (mode === "callable_table") {
346
358
  const mapping = isRecord(definition.outputMapping) ? definition.outputMapping : {};
347
359
  const fields = Object.entries(mapping).map(([outputKey, target]) => toField({
@@ -1,3 +1,3 @@
1
1
  export declare const OXYGEN_VERSION: string;
2
- export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1011.326";
2
+ export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.1011.440";
3
3
  export declare const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1022.48";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1023.41";
@@ -1,2 +1,2 @@
1
1
  // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
2
- export const OXYGEN_BUILD_VERSION = "1.1022.48";
2
+ export const OXYGEN_BUILD_VERSION = "1.1023.41";
@@ -49,7 +49,7 @@ export const OXYGEN_VERSION = OXYGEN_BUILD_VERSION;
49
49
  // Since 2026-09-28 the release-preparation step advances this literal to the
50
50
  // highest CLI version published on npm for at least 30 days. It never lowers
51
51
  // the floor. The source change lands on dev before the next production release.
52
- export const OXYGEN_MINIMUM_CLI_VERSION = "1.1011.326";
52
+ export const OXYGEN_MINIMUM_CLI_VERSION = "1.1011.440";
53
53
  // The internal GEO export first gains required pagination in this dev version.
54
54
  // Earlier pilot clients would save a partial file without its continuation.
55
55
  export const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -24,6 +24,8 @@ export type WorkflowGraphNodeChange = {
24
24
  export type WorkflowGraphDiff = {
25
25
  triggerChanged: boolean;
26
26
  inputSchemaChanged: boolean;
27
+ /** The declared run result (`manifest.output`) changed: callers read a different shape. */
28
+ outputChanged: boolean;
27
29
  nodes: WorkflowGraphNodeChange[];
28
30
  edgesAdded: number;
29
31
  edgesRemoved: number;
@@ -60,14 +60,17 @@ export function diffWorkflowGraphManifests(before, after) {
60
60
  const edgesRemoved = [...beforeEdges].filter((key) => !afterEdges.has(key)).length;
61
61
  const triggerChanged = stable(before.trigger) !== stable(after.trigger);
62
62
  const inputSchemaChanged = stable(before.input_schema) !== stable(after.input_schema);
63
+ const outputChanged = stable(before.output) !== stable(after.output);
63
64
  return {
64
65
  triggerChanged,
65
66
  inputSchemaChanged,
67
+ outputChanged,
66
68
  nodes: changes,
67
69
  edgesAdded,
68
70
  edgesRemoved,
69
71
  unchanged: !triggerChanged
70
72
  && !inputSchemaChanged
73
+ && !outputChanged
71
74
  && changes.length === 0
72
75
  && edgesAdded === 0
73
76
  && edgesRemoved === 0,
@@ -20,3 +20,4 @@ export * from "./params.js";
20
20
  export * from "./remap.js";
21
21
  export * from "./manifest-schema.js";
22
22
  export * from "./mapping.js";
23
+ export * from "./output.js";
@@ -20,3 +20,4 @@ export * from "./params.js";
20
20
  export * from "./remap.js";
21
21
  export * from "./manifest-schema.js";
22
22
  export * from "./mapping.js";
23
+ export * from "./output.js";
@@ -13,7 +13,8 @@ import { isWorkflowToolRejected, lintRecipeManifest, lintWorkflowCodeSourceSafet
13
13
  import { UNARY_COMPARE_OPS, WORKFLOW_COMPARE_OPS, compileConditionPattern, parseScopePath, referencedScopePaths, SCOPE_PATH_ROOTS, } from "./expression.js";
14
14
  import { missingToolParams, unknownToolParams } from "./params.js";
15
15
  import { danglingEdges, dominatingNodeIds, findIllegalCycles, loopBodyNodeIds, reachableNodeIds, workflowCodeSandboxInvocationUpperBound, } from "./topology.js";
16
- import { MAX_WORKFLOW_LOOP_ITERATIONS, MAX_WORKFLOW_NODE_RETRY_ATTEMPTS, MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS, RESERVED_EDGE_HANDLES, RESERVED_NODE_IDS, isWorkflowCodeFieldName, WORKFLOW_CODE_V1_LANGUAGE, WORKFLOW_CODE_V1_MAX_INPUT_BYTES, WORKFLOW_CODE_V1_MAX_INPUTS, WORKFLOW_CODE_V1_MAX_OUTPUT_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_DEPTH, WORKFLOW_CODE_V1_MAX_SCHEMA_NODES, WORKFLOW_CODE_V1_MAX_SCHEMA_PROPERTIES, WORKFLOW_CODE_V1_MAX_SANDBOX_INVOCATIONS_PER_RUN, WORKFLOW_CODE_V1_MAX_SOURCE_BYTES, WORKFLOW_CODE_V1_MAX_TIMEOUT_MS, WORKFLOW_CODE_V1_MIN_INPUT_BYTES, WORKFLOW_CODE_V1_MIN_OUTPUT_BYTES, WORKFLOW_CODE_V1_MIN_TIMEOUT_MS, WORKFLOW_CODE_V1_RUNTIME, WORKFLOW_CODE_V1_VERSION, WORKFLOW_VALUE_COERCIONS, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, LOOP_BODY_HANDLE, LOOP_DONE_HANDLE, } from "./types.js";
16
+ import { WORKFLOW_OUTPUT_FIELD_KEY_PATTERN, WORKFLOW_OUTPUT_MAX_FIELDS } from "./output.js";
17
+ import { WORKFLOW_OUTPUT_FIELD_TYPES, MAX_WORKFLOW_LOOP_ITERATIONS, MAX_WORKFLOW_NODE_RETRY_ATTEMPTS, MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS, RESERVED_EDGE_HANDLES, RESERVED_NODE_IDS, isWorkflowCodeFieldName, WORKFLOW_CODE_V1_LANGUAGE, WORKFLOW_CODE_V1_MAX_INPUT_BYTES, WORKFLOW_CODE_V1_MAX_INPUTS, WORKFLOW_CODE_V1_MAX_OUTPUT_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_BYTES, WORKFLOW_CODE_V1_MAX_SCHEMA_DEPTH, WORKFLOW_CODE_V1_MAX_SCHEMA_NODES, WORKFLOW_CODE_V1_MAX_SCHEMA_PROPERTIES, WORKFLOW_CODE_V1_MAX_SANDBOX_INVOCATIONS_PER_RUN, WORKFLOW_CODE_V1_MAX_SOURCE_BYTES, WORKFLOW_CODE_V1_MAX_TIMEOUT_MS, WORKFLOW_CODE_V1_MIN_INPUT_BYTES, WORKFLOW_CODE_V1_MIN_OUTPUT_BYTES, WORKFLOW_CODE_V1_MIN_TIMEOUT_MS, WORKFLOW_CODE_V1_RUNTIME, WORKFLOW_CODE_V1_VERSION, WORKFLOW_VALUE_COERCIONS, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, LOOP_BODY_HANDLE, LOOP_DONE_HANDLE, } from "./types.js";
17
18
  const NODE_KINDS = new Set([
18
19
  "trigger",
19
20
  "tool",
@@ -119,6 +120,8 @@ export function lintWorkflowGraphManifest(value, options = {}) {
119
120
  // segment of a `steps.` / `loop.` path names a NODE, and that id is the one
120
121
  // part of a hand-typed path this linter can always check.
121
122
  const scope = nodeScopeIndex(value.nodes);
123
+ if (value.output !== undefined)
124
+ lintWorkflowOutput(value.output, "$.output", add, scope);
122
125
  const nodesSound = lintNodes(value.nodes, add, scope, options);
123
126
  const edgesSound = lintEdges(value.edges, value.nodes, add);
124
127
  // Graph-level analysis dereferences every node and edge, so it only runs once
@@ -909,6 +912,46 @@ function lintLoopNode(node, path, add, scope) {
909
912
  add(`${path}.concurrency`, "invalid_loop_target", "Loop bodies run one item at a time. Remove concurrency, or set it to 1.");
910
913
  }
911
914
  }
915
+ /** `manifest.output`: the run's declared result (see ./output.ts). */
916
+ function lintWorkflowOutput(output, path, add, scope) {
917
+ if (!isRecord(output)) {
918
+ add(path, "invalid_output", "Workflow output must be an object with a fields array.");
919
+ return;
920
+ }
921
+ const fields = asArray(output.fields);
922
+ if (!fields || fields.length === 0) {
923
+ add(`${path}.fields`, "invalid_output_field", "Workflow output requires at least one field.");
924
+ return;
925
+ }
926
+ if (fields.length > WORKFLOW_OUTPUT_MAX_FIELDS) {
927
+ add(`${path}.fields`, "invalid_output_field", `Workflow output cannot declare more than ${WORKFLOW_OUTPUT_MAX_FIELDS} fields.`);
928
+ }
929
+ const seen = new Set();
930
+ fields.forEach((field, index) => {
931
+ const fieldPath = `${path}.fields.${index}`;
932
+ if (!isRecord(field)) {
933
+ add(fieldPath, "invalid_output_field", "Output field must be an object.");
934
+ return;
935
+ }
936
+ if (!isNonEmptyString(field.key) || !WORKFLOW_OUTPUT_FIELD_KEY_PATTERN.test(field.key)) {
937
+ add(`${fieldPath}.key`, "invalid_output_field", "Output field key must start with a letter or underscore and use only letters, digits and underscores.");
938
+ }
939
+ else if (seen.has(field.key)) {
940
+ add(`${fieldPath}.key`, "duplicate_output_field", `Output field '${field.key}' is declared twice.`);
941
+ }
942
+ else {
943
+ seen.add(field.key);
944
+ }
945
+ if (field.type !== undefined
946
+ && !WORKFLOW_OUTPUT_FIELD_TYPES.includes(field.type)) {
947
+ add(`${fieldPath}.type`, "invalid_output_field", `Output field type must be one of ${WORKFLOW_OUTPUT_FIELD_TYPES.join(", ")}.`);
948
+ }
949
+ if (field.description !== undefined && typeof field.description !== "string") {
950
+ add(`${fieldPath}.description`, "invalid_output_field", "Output field description must be a string.");
951
+ }
952
+ validateValueRef(field.value, `${fieldPath}.value`, add, scope);
953
+ });
954
+ }
912
955
  function lintSetNode(node, path, add, scope) {
913
956
  const fields = asArray(node.fields);
914
957
  if (!fields || fields.length === 0) {
@@ -187,6 +187,37 @@ export declare const workflowGraphManifestSchema: {
187
187
  readonly type: "object";
188
188
  readonly additionalProperties: true;
189
189
  };
190
+ readonly output: {
191
+ readonly type: "object";
192
+ readonly description: string;
193
+ readonly properties: {
194
+ readonly fields: {
195
+ readonly type: "array";
196
+ readonly minItems: 1;
197
+ readonly items: {
198
+ readonly type: "object";
199
+ readonly properties: {
200
+ readonly key: {
201
+ readonly type: "string";
202
+ readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
203
+ };
204
+ readonly value: {
205
+ readonly type: "object";
206
+ readonly additionalProperties: true;
207
+ };
208
+ readonly type: {
209
+ readonly enum: readonly ["string", "number", "integer", "boolean", "object", "array"];
210
+ };
211
+ readonly description: {
212
+ readonly type: "string";
213
+ };
214
+ };
215
+ readonly required: readonly ["key", "value"];
216
+ };
217
+ };
218
+ };
219
+ readonly required: readonly ["fields"];
220
+ };
190
221
  readonly nodes: {
191
222
  readonly type: "array";
192
223
  readonly items: {
@@ -1064,6 +1095,37 @@ export declare const portableWorkflowDefinitionSchema: {
1064
1095
  readonly type: "object";
1065
1096
  readonly additionalProperties: true;
1066
1097
  };
1098
+ readonly output: {
1099
+ readonly type: "object";
1100
+ readonly description: string;
1101
+ readonly properties: {
1102
+ readonly fields: {
1103
+ readonly type: "array";
1104
+ readonly minItems: 1;
1105
+ readonly items: {
1106
+ readonly type: "object";
1107
+ readonly properties: {
1108
+ readonly key: {
1109
+ readonly type: "string";
1110
+ readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
1111
+ };
1112
+ readonly value: {
1113
+ readonly type: "object";
1114
+ readonly additionalProperties: true;
1115
+ };
1116
+ readonly type: {
1117
+ readonly enum: readonly ["string", "number", "integer", "boolean", "object", "array"];
1118
+ };
1119
+ readonly description: {
1120
+ readonly type: "string";
1121
+ };
1122
+ };
1123
+ readonly required: readonly ["key", "value"];
1124
+ };
1125
+ };
1126
+ };
1127
+ readonly required: readonly ["fields"];
1128
+ };
1067
1129
  readonly nodes: {
1068
1130
  readonly type: "array";
1069
1131
  readonly items: {
@@ -369,6 +369,28 @@ export const workflowGraphManifestSchema = {
369
369
  specification: { type: "string" },
370
370
  trigger: { type: "object", additionalProperties: true, description: "See the 'trigger' schema subject." },
371
371
  input_schema: { type: "object", additionalProperties: true },
372
+ output: {
373
+ type: "object",
374
+ description: "The run's declared result, stored as output.result. Required before a Table workflow column can call the workflow."
375
+ + " Each field's value is a value ref resolved after the last node; a branch that did not run yields null.",
376
+ properties: {
377
+ fields: {
378
+ type: "array",
379
+ minItems: 1,
380
+ items: {
381
+ type: "object",
382
+ properties: {
383
+ key: { type: "string", pattern: "^[A-Za-z_][A-Za-z0-9_]*$" },
384
+ value: { type: "object", additionalProperties: true },
385
+ type: { enum: ["string", "number", "integer", "boolean", "object", "array"] },
386
+ description: { type: "string" },
387
+ },
388
+ required: ["key", "value"],
389
+ },
390
+ },
391
+ },
392
+ required: ["fields"],
393
+ },
372
394
  nodes: { type: "array", items: nodeSchema, minItems: 1 },
373
395
  edges: { type: "array", items: edgeSchema },
374
396
  max_credits: { type: "number", exclusiveMinimum: 0, description: "Per-RUN managed-credit ceiling." },
@@ -0,0 +1,36 @@
1
+ import type { JsonSchema } from "../manifest-validation.js";
2
+ import { type WorkflowRunScope } from "./expression.js";
3
+ import type { WorkflowGraphManifest, WorkflowOutputDeclaration, WorkflowOutputFieldType } from "./types.js";
4
+ /** Keys become `{{column.key}}` tokens in a calling Table, so they stay identifier-shaped. */
5
+ export declare const WORKFLOW_OUTPUT_FIELD_KEY_PATTERN: RegExp;
6
+ export declare const WORKFLOW_OUTPUT_MAX_FIELDS = 50;
7
+ export declare class WorkflowOutputTypeError extends Error {
8
+ readonly key: string;
9
+ readonly expected: WorkflowOutputFieldType;
10
+ readonly code = "workflow_output_type_mismatch";
11
+ constructor(key: string, expected: WorkflowOutputFieldType);
12
+ }
13
+ /** The declared output as a closed JSON Schema, or null when the workflow declares none. */
14
+ export declare function workflowOutputSchema(output: WorkflowOutputDeclaration | undefined): JsonSchema | null;
15
+ /**
16
+ * Resolve every declared field against the finished run's scope.
17
+ *
18
+ * A path into a branch that did not run yields null rather than failing the
19
+ * run: "no value" is an honest result. A value of the wrong declared type
20
+ * fails, after the same fail-closed scalar conversion a mapped node input gets.
21
+ */
22
+ export declare function resolveWorkflowOutput(output: WorkflowOutputDeclaration, scope: WorkflowRunScope): Record<string, unknown>;
23
+ export type WorkflowTableCallableIssue = {
24
+ code: "missing_output" | "trigger_not_api" | "blocking_node" | "durable_recipe_node";
25
+ message: string;
26
+ nodeId?: string;
27
+ };
28
+ /**
29
+ * Can a Table column call this workflow once per row?
30
+ *
31
+ * A cell must settle without a person: approval and wait nodes would park rows
32
+ * for hours, and a durable recipe may do either inside its bundle. Only an
33
+ * `api` trigger is allowed so the workflow has no second life as a cron,
34
+ * webhook or event automation that a column edit would silently change.
35
+ */
36
+ export declare function workflowTableCallableIssues(manifest: Pick<WorkflowGraphManifest, "output" | "trigger" | "nodes">): WorkflowTableCallableIssue[];
@@ -0,0 +1,111 @@
1
+ import { coerceWorkflowValue, resolveValueRef } from "./expression.js";
2
+ /** Keys become `{{column.key}}` tokens in a calling Table, so they stay identifier-shaped. */
3
+ export const WORKFLOW_OUTPUT_FIELD_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
4
+ export const WORKFLOW_OUTPUT_MAX_FIELDS = 50;
5
+ export class WorkflowOutputTypeError extends Error {
6
+ key;
7
+ expected;
8
+ code = "workflow_output_type_mismatch";
9
+ constructor(key, expected) {
10
+ super(`Output field '${key}' must be ${expected === "integer" ? "an integer" : `a ${expected}`}.`);
11
+ this.key = key;
12
+ this.expected = expected;
13
+ this.name = "WorkflowOutputTypeError";
14
+ }
15
+ }
16
+ /** The declared output as a closed JSON Schema, or null when the workflow declares none. */
17
+ export function workflowOutputSchema(output) {
18
+ if (!output || output.fields.length === 0)
19
+ return null;
20
+ const properties = {};
21
+ for (const field of output.fields) {
22
+ const schema = field.type ? { type: [field.type, "null"] } : {};
23
+ if (field.description)
24
+ schema.description = field.description;
25
+ properties[field.key] = schema;
26
+ }
27
+ return { type: "object", properties, additionalProperties: false };
28
+ }
29
+ /**
30
+ * Resolve every declared field against the finished run's scope.
31
+ *
32
+ * A path into a branch that did not run yields null rather than failing the
33
+ * run: "no value" is an honest result. A value of the wrong declared type
34
+ * fails, after the same fail-closed scalar conversion a mapped node input gets.
35
+ */
36
+ export function resolveWorkflowOutput(output, scope) {
37
+ const result = {};
38
+ for (const field of output.fields) {
39
+ result[field.key] = typedOutputValue(field, resolveValueRef(field.value, scope));
40
+ }
41
+ return result;
42
+ }
43
+ function typedOutputValue(field, value) {
44
+ if (value === undefined || value === null)
45
+ return null;
46
+ switch (field.type) {
47
+ case undefined:
48
+ return value;
49
+ case "string":
50
+ case "number":
51
+ case "integer":
52
+ case "boolean":
53
+ try {
54
+ return coerceWorkflowValue(value, field.type);
55
+ }
56
+ catch {
57
+ throw new WorkflowOutputTypeError(field.key, field.type);
58
+ }
59
+ case "object":
60
+ if (typeof value === "object" && !Array.isArray(value))
61
+ return value;
62
+ throw new WorkflowOutputTypeError(field.key, field.type);
63
+ case "array":
64
+ if (Array.isArray(value))
65
+ return value;
66
+ throw new WorkflowOutputTypeError(field.key, field.type);
67
+ }
68
+ }
69
+ /**
70
+ * Can a Table column call this workflow once per row?
71
+ *
72
+ * A cell must settle without a person: approval and wait nodes would park rows
73
+ * for hours, and a durable recipe may do either inside its bundle. Only an
74
+ * `api` trigger is allowed so the workflow has no second life as a cron,
75
+ * webhook or event automation that a column edit would silently change.
76
+ */
77
+ export function workflowTableCallableIssues(manifest) {
78
+ const issues = [];
79
+ if (!manifest.output || manifest.output.fields.length === 0) {
80
+ issues.push({
81
+ code: "missing_output",
82
+ message: "Declare at least one output field; the column cell shows the workflow's output.",
83
+ });
84
+ }
85
+ const triggerType = manifest.trigger?.type ?? "api";
86
+ if (triggerType !== "api") {
87
+ issues.push({
88
+ code: "trigger_not_api",
89
+ message: `A workflow a column calls must use the api trigger, not ${triggerType}.`,
90
+ });
91
+ }
92
+ for (const node of manifest.nodes) {
93
+ if (node.disabled === true)
94
+ continue;
95
+ if (node.kind === "approval" || node.kind === "wait") {
96
+ issues.push({
97
+ code: "blocking_node",
98
+ nodeId: node.id,
99
+ message: `Remove the ${node.kind} step '${node.name}': a column cell cannot wait for it.`,
100
+ });
101
+ }
102
+ else if (node.kind === "code" && node.recipe !== undefined) {
103
+ issues.push({
104
+ code: "durable_recipe_node",
105
+ nodeId: node.id,
106
+ message: `Replace the durable recipe step '${node.name}': it may wait or ask for approval.`,
107
+ });
108
+ }
109
+ }
110
+ return issues;
111
+ }
@@ -416,6 +416,23 @@ export type WorkflowGraphEdge = {
416
416
  source_handle?: string;
417
417
  target: string;
418
418
  };
419
+ export declare const WORKFLOW_OUTPUT_FIELD_TYPES: readonly ["string", "number", "integer", "boolean", "object", "array"];
420
+ export type WorkflowOutputFieldType = typeof WORKFLOW_OUTPUT_FIELD_TYPES[number];
421
+ /** One named value of a run's result, resolved after the last node finishes. */
422
+ export type WorkflowOutputField = {
423
+ key: string;
424
+ value: WorkflowValueRef;
425
+ type?: WorkflowOutputFieldType;
426
+ description?: string;
427
+ };
428
+ /**
429
+ * What a run returns. Without it a finished run only exposes every node's raw
430
+ * output; with it, callers (a Table workflow column, MCP, `workflows run`) read
431
+ * `output.result` and know its shape before the first run.
432
+ */
433
+ export type WorkflowOutputDeclaration = {
434
+ fields: WorkflowOutputField[];
435
+ };
419
436
  export type WorkflowGraphManifest = {
420
437
  manifest_version: typeof WORKFLOW_GRAPH_MANIFEST_VERSION;
421
438
  workflow: {
@@ -426,6 +443,8 @@ export type WorkflowGraphManifest = {
426
443
  specification?: string;
427
444
  trigger?: WorkflowTriggerManifest;
428
445
  input_schema?: JsonSchema;
446
+ /** The run's declared result; see WorkflowOutputDeclaration. */
447
+ output?: WorkflowOutputDeclaration;
429
448
  nodes: WorkflowGraphNode[];
430
449
  edges: WorkflowGraphEdge[];
431
450
  /** Per-RUN managed-credit ceiling, same semantics as WorkflowManifest.max_credits. */
@@ -135,6 +135,14 @@ export const WORKFLOW_CODE_V1_DEFAULT_LIMITS = {
135
135
  /** Bounds on a node's own retry budget. */
136
136
  export const MAX_WORKFLOW_NODE_RETRY_ATTEMPTS = 5;
137
137
  export const MAX_WORKFLOW_NODE_RETRY_WAIT_SECONDS = 3_600;
138
+ export const WORKFLOW_OUTPUT_FIELD_TYPES = [
139
+ "string",
140
+ "number",
141
+ "integer",
142
+ "boolean",
143
+ "object",
144
+ "array",
145
+ ];
138
146
  function isRecord(value) {
139
147
  return typeof value === "object" && value !== null && !Array.isArray(value);
140
148
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxygen-agent/cli",
3
- "version": "1.1022.48",
3
+ "version": "1.1023.41",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",