@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.
- package/README.md +1 -1
- package/dist/command-families/tables/register-views.js +3 -3
- package/dist/commands/approvals.js +1 -1
- package/dist/commands/members.js +1 -1
- package/dist/commands/orgs.js +1 -1
- package/dist/commands/publishing.js +10 -10
- package/dist/commands/sequences.js +6 -0
- package/node_modules/@oxygen/shared/dist/access/roles.d.ts +21 -8
- package/node_modules/@oxygen/shared/dist/access/roles.js +53 -16
- package/node_modules/@oxygen/shared/dist/capability-routes/geo.js +1 -1
- package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js +1 -1
- package/node_modules/@oxygen/shared/dist/contracts/geo.js +4 -4
- package/node_modules/@oxygen/shared/dist/geo/geo.js +1 -1
- package/node_modules/@oxygen/shared/dist/publishing/limits.d.ts +7 -0
- package/node_modules/@oxygen/shared/dist/publishing/limits.js +7 -0
- package/node_modules/@oxygen/shared/dist/social-capabilities.js +5 -3
- package/node_modules/@oxygen/shared/dist/tables/column-output-fields.js +12 -0
- package/node_modules/@oxygen/shared/dist/version.d.ts +1 -1
- package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
- package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
- package/node_modules/@oxygen/shared/dist/version.js +1 -1
- package/node_modules/@oxygen/workflows/dist/graph/diff.d.ts +2 -0
- package/node_modules/@oxygen/workflows/dist/graph/diff.js +3 -0
- package/node_modules/@oxygen/workflows/dist/graph/index.d.ts +1 -0
- package/node_modules/@oxygen/workflows/dist/graph/index.js +1 -0
- package/node_modules/@oxygen/workflows/dist/graph/lint.js +44 -1
- package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.d.ts +62 -0
- package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.js +22 -0
- package/node_modules/@oxygen/workflows/dist/graph/output.d.ts +36 -0
- package/node_modules/@oxygen/workflows/dist/graph/output.js +111 -0
- package/node_modules/@oxygen/workflows/dist/graph/types.d.ts +19 -0
- package/node_modules/@oxygen/workflows/dist/graph/types.js +8 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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)
|
|
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)
|
|
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
|
|
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);
|
package/dist/commands/members.js
CHANGED
|
@@ -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
|
|
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.")
|
package/dist/commands/orgs.js
CHANGED
|
@@ -224,7 +224,7 @@ export function registerOrgsFamily(program, handleAsyncAction) {
|
|
|
224
224
|
}));
|
|
225
225
|
}))
|
|
226
226
|
.addCommand(new Command("member-role")
|
|
227
|
-
.description("
|
|
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
|
|
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
|
|
809
|
-
.option("--video-thumbnail-file <path>", "Upload a local
|
|
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
|
|
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
|
|
850
|
-
.option("--video-thumbnail-file <path>", "Upload a local
|
|
851
|
-
.option("--clear-video-thumbnail", "Remove the
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
|
|
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
|
|
56
|
-
* holds. If it ever does, the safe reading of a broken
|
|
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
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
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,
|
|
11
|
-
//
|
|
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
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
* apps/web/src/lib/access/role-access.ts) so
|
|
86
|
-
*
|
|
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
|
|
89
|
-
* holds. If it ever does, the safe reading of a broken
|
|
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
|
|
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: "
|
|
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
|
|
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
|
|
79
|
-
operation("projects.create", "/projects", "POST", "projects create", "Create a
|
|
80
|
-
operation("projects.get", "/projects/{project_id}", "GET", "projects get", "Read a
|
|
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
|
|
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", "
|
|
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: "
|
|
89
|
+
status: "limited",
|
|
90
90
|
source: "provider",
|
|
91
|
-
|
|
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: "
|
|
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 +1 @@
|
|
|
1
|
-
export declare const OXYGEN_BUILD_VERSION = "1.
|
|
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.
|
|
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.
|
|
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,
|
|
@@ -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 {
|
|
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
|
}
|