@oxygen-agent/cli 1.1022.49 → 1.1024.24

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 (62) hide show
  1. package/README.md +1 -1
  2. package/dist/command-families/program.js +0 -4
  3. package/dist/command-families/tables/register-views.js +3 -3
  4. package/dist/command-manifest.js +0 -2
  5. package/dist/commands/approvals.js +1 -1
  6. package/dist/commands/budget.js +9 -4
  7. package/dist/commands/companies.js +1 -1
  8. package/dist/commands/members.js +1 -1
  9. package/dist/commands/orgs.js +1 -1
  10. package/dist/commands/publishing.js +25 -16
  11. package/dist/commands/sequences.js +15 -1
  12. package/dist/commands/workflows.js +1 -1
  13. package/node_modules/@oxygen/shared/dist/access/permissions.d.ts +1 -1
  14. package/node_modules/@oxygen/shared/dist/access/permissions.js +1 -1
  15. package/node_modules/@oxygen/shared/dist/access/roles.d.ts +21 -8
  16. package/node_modules/@oxygen/shared/dist/access/roles.js +53 -16
  17. package/node_modules/@oxygen/shared/dist/billing/budget-scopes.d.ts +2 -2
  18. package/node_modules/@oxygen/shared/dist/billing/budget-scopes.js +2 -2
  19. package/node_modules/@oxygen/shared/dist/billing/plan-capabilities.js +1 -1
  20. package/node_modules/@oxygen/shared/dist/capability-intents/index.generated.d.ts +0 -40
  21. package/node_modules/@oxygen/shared/dist/capability-intents/tables.d.ts +0 -20
  22. package/node_modules/@oxygen/shared/dist/capability-intents/tables.js +0 -3
  23. package/node_modules/@oxygen/shared/dist/capability-intents/tables.rules.js +6 -41
  24. package/node_modules/@oxygen/shared/dist/capability-routes/geo.js +1 -1
  25. package/node_modules/@oxygen/shared/dist/capability-routes/tables.js +3 -3
  26. package/node_modules/@oxygen/shared/dist/contracts/browser-operations.js +1 -0
  27. package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js +1 -1
  28. package/node_modules/@oxygen/shared/dist/contracts/geo.js +6 -6
  29. package/node_modules/@oxygen/shared/dist/copilot/plan-hold.d.ts +1 -0
  30. package/node_modules/@oxygen/shared/dist/copilot/plan-hold.js +5 -2
  31. package/node_modules/@oxygen/shared/dist/geo/geo.d.ts +168 -2
  32. package/node_modules/@oxygen/shared/dist/geo/geo.js +358 -71
  33. package/node_modules/@oxygen/shared/dist/onboarding-leads.js +9 -3
  34. package/node_modules/@oxygen/shared/dist/publishing/limits.d.ts +7 -0
  35. package/node_modules/@oxygen/shared/dist/publishing/limits.js +7 -0
  36. package/node_modules/@oxygen/shared/dist/schedule-label.js +29 -1
  37. package/node_modules/@oxygen/shared/dist/sequences/enrollment-origin.d.ts +3 -1
  38. package/node_modules/@oxygen/shared/dist/sequences/enrollment-origin.js +2 -0
  39. package/node_modules/@oxygen/shared/dist/social-capabilities.js +5 -3
  40. package/node_modules/@oxygen/shared/dist/tables/column-output-fields.js +12 -0
  41. package/node_modules/@oxygen/shared/dist/version.d.ts +1 -1
  42. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  43. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  44. package/node_modules/@oxygen/shared/dist/version.js +1 -1
  45. package/node_modules/@oxygen/workflows/dist/graph/diff.d.ts +2 -0
  46. package/node_modules/@oxygen/workflows/dist/graph/diff.js +3 -0
  47. package/node_modules/@oxygen/workflows/dist/graph/index.d.ts +1 -0
  48. package/node_modules/@oxygen/workflows/dist/graph/index.js +1 -0
  49. package/node_modules/@oxygen/workflows/dist/graph/lint.js +44 -1
  50. package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.d.ts +62 -0
  51. package/node_modules/@oxygen/workflows/dist/graph/manifest-schema.js +22 -0
  52. package/node_modules/@oxygen/workflows/dist/graph/output.d.ts +36 -0
  53. package/node_modules/@oxygen/workflows/dist/graph/output.js +111 -0
  54. package/node_modules/@oxygen/workflows/dist/graph/types.d.ts +19 -0
  55. package/node_modules/@oxygen/workflows/dist/graph/types.js +8 -0
  56. package/package.json +1 -1
  57. package/dist/commands/callables.d.ts +0 -3
  58. package/dist/commands/callables.js +0 -111
  59. package/dist/functions-commands.d.ts +0 -6
  60. package/dist/functions-commands.js +0 -85
  61. package/node_modules/@oxygen/shared/dist/contracts/function-library-read.d.ts +0 -14
  62. package/node_modules/@oxygen/shared/dist/contracts/function-library-read.js +0 -16
@@ -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.446";
3
3
  export declare const GEO_EXPORT_MINIMUM_CLI_VERSION = "1.1013.0";
@@ -1 +1 @@
1
- export declare const OXYGEN_BUILD_VERSION = "1.1022.49";
1
+ export declare const OXYGEN_BUILD_VERSION = "1.1024.24";
@@ -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.49";
2
+ export const OXYGEN_BUILD_VERSION = "1.1024.24";
@@ -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.446";
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.49",
3
+ "version": "1.1024.24",
4
4
  "private": false,
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -1,3 +0,0 @@
1
- import { ExtractedCommandActionHandler } from "../command-support.js";
2
- import { Command } from "commander";
3
- export declare function registerCallablesFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;
@@ -1,111 +0,0 @@
1
- import { parseJsonObject, readPositiveInt } from "../cli-values.js";
2
- import { parseJsonArray, readPositiveNumber } from "../command-support.js";
3
- import { requestOxygen } from "../http-client.js";
4
- import { readOption } from "../util.js";
5
- import { Command } from "commander";
6
- export function registerCallablesFamily(program, handleAsyncAction) {
7
- program
8
- .command("callables")
9
- .description("Publish and bind typed callable tables (reusable row-in/row-out table runs).")
10
- .addCommand(new Command("publish")
11
- .description("Publish an existing table as a versioned callable function.")
12
- .argument("<table>", "Backing table id or slug.")
13
- .requiredOption("--inputs-json <json>", "JSON array of inputs: [{column,key?,required?,description?}].")
14
- .requiredOption("--actions-json <json>", "JSON array of executable backing-table column keys or ids.")
15
- .requiredOption("--outputs-json <json>", "JSON array of outputs: [{column,key?,required?,description?}].")
16
- .requiredOption("--max-credits-per-item <n>", "Default hard credit ceiling for one enrolled caller row.")
17
- .option("--max-items <n>", "Default maximum source rows per invocation. Defaults to 100.")
18
- .option("--slug <slug>", "Stable callable slug.")
19
- .option("--name <name>", "Callable display name.")
20
- .option("--description <text>", "What the callable does and when to use it.")
21
- .option("--json", "Print a JSON envelope.")
22
- .action(async (table, options) => {
23
- await handleAsyncAction("callables publish", options, () => requestOxygen("/api/cli/callables", {
24
- method: "POST",
25
- body: {
26
- table,
27
- inputs: parseJsonArray(options.inputsJson),
28
- action_columns: parseJsonArray(options.actionsJson),
29
- outputs: parseJsonArray(options.outputsJson),
30
- default_max_credits_per_item: readPositiveNumber(options.maxCreditsPerItem),
31
- ...(readPositiveInt(options.maxItems) !== undefined
32
- ? { default_max_items: readPositiveInt(options.maxItems) }
33
- : {}),
34
- ...(readOption(options.slug) ? { slug: readOption(options.slug) } : {}),
35
- ...(readOption(options.name) ? { display_name: readOption(options.name) } : {}),
36
- ...(readOption(options.description) ? { description: readOption(options.description) } : {}),
37
- },
38
- }));
39
- }))
40
- .addCommand(new Command("list")
41
- .description("List published callable tables and their current credit posture.")
42
- .option("--include-disabled", "Include disabled definitions.")
43
- .option("--limit <n>", "Maximum definitions to return.")
44
- .option("--json", "Print a JSON envelope.")
45
- .action(async (options) => {
46
- await handleAsyncAction("callables list", options, () => {
47
- const params = new URLSearchParams();
48
- if (options.includeDisabled)
49
- params.set("include_disabled", "true");
50
- if (readPositiveInt(options.limit) !== undefined)
51
- params.set("limit", String(readPositiveInt(options.limit)));
52
- const suffix = params.toString();
53
- return requestOxygen(`/api/cli/callables${suffix ? `?${suffix}` : ""}`);
54
- });
55
- }))
56
- .addCommand(new Command("describe")
57
- .description("Describe a callable's typed input/output contract and pinned backing columns.")
58
- .argument("<callable>", "Callable id, slug, backing table id, or backing table slug.")
59
- .option("--include-disabled", "Allow a disabled callable.")
60
- .option("--json", "Print a JSON envelope.")
61
- .action(async (callable, options) => {
62
- await handleAsyncAction("callables describe", options, () => {
63
- const params = new URLSearchParams({ callable });
64
- if (options.includeDisabled)
65
- params.set("include_disabled", "true");
66
- return requestOxygen(`/api/cli/callables?${params.toString()}`);
67
- });
68
- }))
69
- .addCommand(new Command("bind")
70
- .description("Add a callable-function column to a source table with explicit input and callback mappings.")
71
- .argument("<table>", "Caller/source table id or slug.")
72
- .argument("<callable>", "Callable id or slug.")
73
- .requiredOption("--inputs-json <json>", "JSON object mapping callable input keys to source column keys.")
74
- .requiredOption("--outputs-json <json>", "JSON object mapping callable output keys to callback target column keys.")
75
- .option("--max-credits-per-item <n>", "Override the callable's default per-enrolled-row cap.")
76
- .option("--overwrite-policy <policy>", "empty_only (default) or overwrite.")
77
- .option("--key <key>", "Binding column key.")
78
- .option("--label <label>", "Binding column label.")
79
- .option("--json", "Print a JSON envelope.")
80
- .action(async (table, callable, options) => {
81
- await handleAsyncAction("callables bind", options, () => requestOxygen("/api/cli/callables/bind", {
82
- method: "POST",
83
- body: {
84
- table,
85
- callable,
86
- input_mapping: parseJsonObject(options.inputsJson),
87
- output_mapping: parseJsonObject(options.outputsJson),
88
- ...(readPositiveNumber(options.maxCreditsPerItem) !== undefined
89
- ? { max_credits_per_item: readPositiveNumber(options.maxCreditsPerItem) }
90
- : {}),
91
- ...(readOption(options.overwritePolicy) ? { overwrite_policy: readOption(options.overwritePolicy) } : {}),
92
- ...(readOption(options.key) ? { key: readOption(options.key) } : {}),
93
- ...(readOption(options.label) ? { label: readOption(options.label) } : {}),
94
- },
95
- }));
96
- }))
97
- .addCommand(new Command("enable")
98
- .description("Enable a callable table.")
99
- .argument("<callable>", "Callable id, slug, or backing table.")
100
- .option("--json", "Print a JSON envelope.")
101
- .action(async (callable, options) => {
102
- await handleAsyncAction("callables enable", options, () => requestOxygen("/api/cli/callables/status", { method: "POST", body: { callable, status: "active" } }));
103
- }))
104
- .addCommand(new Command("disable")
105
- .description("Disable new invocations without changing existing tables or in-flight runs.")
106
- .argument("<callable>", "Callable id, slug, or backing table.")
107
- .option("--json", "Print a JSON envelope.")
108
- .action(async (callable, options) => {
109
- await handleAsyncAction("callables disable", options, () => requestOxygen("/api/cli/callables/status", { method: "POST", body: { callable, status: "disabled" } }));
110
- }));
111
- }
@@ -1,6 +0,0 @@
1
- import { Command } from "commander";
2
- type JsonOptions = {
3
- json?: boolean;
4
- };
5
- export declare function registerFunctionsCommands(program: Command, handle: (command: string, options: JsonOptions, action: () => Promise<unknown>) => Promise<void>): void;
6
- export {};