@oxygen-agent/cli 1.739.1 → 1.750.4

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.739.1
+Version: 1.750.4

package/dist/command-manifest.js

@@ -32,7 +32,7 @@ const MUTATING_VERBS = new Set([
     "billing-link", "billing-unlink",
     "bind", "buy", "call", "cancel", "chat-action", "claim", "clear",
     "comment", "configure", "connect", "create", "decide", "delete", "delist", "disable",
-    "disconnect", "dispatch", "draft", "duplicate", "edit", "emit", "enable", "enroll",
+    "disconnect", "dispatch", "done", "draft", "duplicate", "edit", "emit", "enable", "enroll",
     "file", "forward", "grant", "harvest", "history", "import", "insert", "interrupt", "invite",
     "label-add", "label-remove", "launch", "log", "login", "logout", "mark-all-read", "mark-read", "materialize", "merge",
     "migrate",
@@ -54,6 +54,10 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
     // Credential replacement is destructive but does not execute the graph,
     // call a provider, or spend Oxygen credits.
     "workflows webhooks rotate",
+    // These flags describe a hypothetical autonomous grant to the shared
+    // readiness validator. Lint remains read-only and can never create the
+    // grant, call a node/provider, or spend the candidate ceiling.
+    "workflows lint",
 ]);
 // Exact noun-style reads whose leaf happens to look like a mutating verb.
 // `workflows run <id>` gets an existing Workflow run; `workflows call` creates
@@ -64,6 +68,7 @@ const READ_ONLY_COMMANDS = new Set(["workflows run"]);
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
     "mailboxes delete",
+    "support admin done",
     "support admin reply",
     "workflows webhooks rotate",
 ]);

package/dist/index.js

@@ -2655,9 +2655,9 @@ export function createProgram() {
     }));
     program
         .command("support")
-        .description("Open and track Plain support conversations for the active OXYGEN organization. Filing is a zero-credit write to the canonical Plain queue.")
+        .description("Open and track Plain support conversations for the active OXYGEN organization. In the app, use Settings → Support → Open support chat. Retry is the only recovery control; it returns after each failed connection attempt and never creates a Thread. CLI filing is a zero-credit write to the canonical Plain queue. Guide: https://oxygen-agent.com/docs/surfaces/support.")
         .addCommand(new Command("file")
-        .description("Create a real, zero-credit Plain support Thread immediately. There is no preview: review the exact subject, body, category, and severity before running it. Use when you're stuck on an OXYGEN operation.")
+        .description("Create a real, zero-credit Plain support Thread immediately. This is a separate filing action, not the in-app Retry, and can create a second Thread: check `support list --status open` first and reply to the existing Thread for the same issue. There is no preview: review the exact subject, body, category, and severity before running it. Use when you're stuck on an OXYGEN operation.")
         .requiredOption("--subject <subject>", "One-line summary of the problem.")
         .option("--body <body>", "What you were doing, what happened, and what you tried.")
         .option("--severity <severity>", "low | normal | high. Defaults to normal.")
@@ -2801,19 +2801,54 @@ export function createProgram() {
         });
     }))
         .addCommand(new Command("reply")
-        .description("Preview or send a public reply on the Thread's native Plain channel (human staff only; sent as Oxygen Support).")
+        .description("Preview or send a guarded public reply on the Thread's native Plain channel as Oxygen Support (staff only). CLI delivery is agent-only; named humans use Plain Inbox or Plain MCP.")
         .argument("<ticketId>", "Plain Thread ID (th_...).")
         .requiredOption("--body <body>", "Customer-visible reply body.")
+        .requiredOption("--agent", "Required safety declaration: reply as the authenticated Oxygen Support machine user after it owns the Thread.")
         .option("--confirm-ref <ref>", "Send only when this exactly matches the previewed Plain ref (for example T-10). Omit to preview without sending.")
+        .option("--confirm-message <messageId>", "Agent send only: confirm the latest customer message ID returned by preview.")
+        .option("--confirm-token <token>", "Agent send only: use the exact server-authenticated preview token bound to the Thread, latest message, reply body, and actor mode; never calculate it locally.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
         await handleAsyncAction("support admin reply", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/messages`, {
             method: "POST",
             body: {
                 body: readOption(options.body),
+                as_agent: true,
                 ...(readOption(options.confirmRef)
                     ? { confirm_ref: readOption(options.confirmRef) }
                     : {}),
+                ...(readOption(options.confirmMessage)
+                    ? { confirm_message_id: readOption(options.confirmMessage) }
+                    : {}),
+                ...(readOption(options.confirmToken)
+                    ? { confirm_token: readOption(options.confirmToken) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("done")
+        .description("Preview or mark a Plain Thread Done after the exact verified agent reply; new customer activity reopens it to Todo (staff only). CLI completion is agent-only.")
+        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .requiredOption("--agent", "Required safety declaration: mark Done as the authenticated Oxygen Support machine user while it still owns the Thread.")
+        .requiredOption("--reply-token <token>", "Use the exact agent_done_token returned by the preceding live `support admin reply --agent`; previews and errors never mint or reveal one.")
+        .option("--confirm-ref <ref>", "Complete only when this exactly matches the previewed Plain ref.")
+        .option("--confirm-message <messageId>", "Complete only when this exactly matches the latest verified staff reply ID from preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (ticketId, options) => {
+        await handleAsyncAction("support admin done", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/resolve`, {
+            method: "POST",
+            body: {
+                as_agent: true,
+                ...(readOption(options.replyToken)
+                    ? { agent_reply_token: readOption(options.replyToken) }
+                    : {}),
+                ...(readOption(options.confirmRef)
+                    ? { confirm_ref: readOption(options.confirmRef) }
+                    : {}),
+                ...(readOption(options.confirmMessage)
+                    ? { confirm_message_id: readOption(options.confirmMessage) }
+                    : {}),
             },
         }));
     }))
@@ -2865,17 +2900,6 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
 `)
         .action(async (options) => {
         await handleAsyncAction("support admin events", options, () => requestOxygen(withSupportEventsQuery("/api/cli/admin/support/events", options)));
-    }), { hidden: true })
-        .addCommand(new Command("resolve")
-        .description("Retired legacy write; always returns the Plain-cutover error (staff only).")
-        .argument("<ticketId>", "Ticket UUID.")
-        .requiredOption("--resolution <text>", "Resolution message sent to the opener.")
-        .option("--json", "Print a JSON envelope.")
-        .action(async (ticketId, options) => {
-        await handleAsyncAction("support admin resolve", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}/resolve`, {
-            method: "POST",
-            body: { resolution: readOption(options.resolution) },
-        }));
     }), { hidden: true })
         .addCommand(new Command("workflow")
         .description("Retired legacy write; Plain notes and downstream engineering work own triage (staff only).")
@@ -14233,12 +14257,14 @@ Fastest editable graph:
   1. oxygen workflows events list --search "<outcome>" --kind builtin --json
   2. oxygen workflows init --id my-workflow
   3. oxygen workflows schema --subject graph --json
-  4. oxygen workflows lint --file my-workflow.workflow.json --json
-  5. oxygen workflows apply --file my-workflow.workflow.json --json
+  4. oxygen workflows lint --file my-workflow.workflow.json --phase draft --json
+  5. oxygen workflows apply --file my-workflow.workflow.json --draft --json
+  6. oxygen workflows lint --file my-workflow.workflow.json --phase publish --json
 
-Applying saves the definition only: it costs 0 credits, calls no graph nodes,
-and creates no run. A disabled workflow stays disabled. Calling or enabling it
-is the separate execution/authorization step.
+Draft apply saves an inert editable revision: it costs 0 credits, calls no graph
+nodes, creates no run, and publishes nothing. After publish lint is clean, apply
+without --draft publishes the revision; calling or enabling it remains a separate
+execution/authorization step.
 
 Run completion:
   Calls enqueue asynchronously. Follow the returned run_id with:
@@ -14335,15 +14361,24 @@ Run completion:
         await handleAsyncAction("workflows init", options, async () => scaffoldWorkflowProject(options));
     }))
         .addCommand(new Command("lint")
-        .description("Compile and lint a workflow file without saving it.")
+        .description("Compile and validate an authored workflow file against the same draft/publish readiness contract as the web editor and apply. Saves nothing, runs nothing, calls no provider, and spends no credits. Portable exports use `workflows import --preflight` because their destination connection bindings are part of validation.")
         .requiredOption("--file <path>", "Workflow module or manifest JSON file.")
+        .addOption(new Option("--phase <phase>", "Validation phase: publish (default) or draft.").choices(["draft", "publish"]).default("publish"))
+        .option("--approved", "Validate that revision-bound autonomous authority is present; grants nothing because lint is read-only.")
+        .option("--max-credits <n>", "Candidate positive per-delivery ceiling; omit to validate the plan default.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("workflows lint", options, async () => {
             const manifest = await compileWorkflowFile(options.file);
+            const maxCredits = readPositiveNumber(options.maxCredits);
             return requestOxygen("/api/cli/workflows/lint", {
                 method: "POST",
-                body: { manifest },
+                body: {
+                    manifest,
+                    phase: options.phase ?? "publish",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
             });
         });
     }))
@@ -14538,9 +14573,9 @@ Run completion:
         },
     }))))
         .addCommand(new Command("replay")
-        .description("Create a new dry run from one authenticated delivery's exact original revision and payload. Never resends the webhook; uses 0 credits, no paid provider calls, and no external writes. Internal reads and outbound HTTP GETs can still execute.")
-        .argument("<delivery_id>", "Delivery UUID from `oxygen workflows webhooks deliveries`.")
-        .option("--request-key <key>", "Stable key for safely retrying the same replay request.")
+        .description("Create a durable, inspectable run in dry_run mode from one verified outcome=ran delivery's exact original revision and payload. Never resends the webhook or adds an inbound delivery-history row; uses 0 credits, no paid provider calls, and no external writes. Internal reads and outbound HTTP GETs can still execute.")
+        .argument("<delivery_id>", "Verified outcome=ran delivery UUID from `oxygen workflows webhooks deliveries`.")
+        .option("--request-key <key>", "Idempotency key. Reusing the same delivery/key returns the existing replay run; it never creates a second run.")
         .option("--json", "Print a JSON envelope.")
         .action((deliveryId, options) => handleAsyncAction("workflows webhooks replay", options, () => requestOxygen("/api/cli/workflows/webhooks/deliveries/replay", {
         method: "POST",
@@ -14550,7 +14585,7 @@ Run completion:
         },
     }))))
         .addCommand(new Command("deliveries")
-        .description("List workflow webhook deliveries: what arrived, whether it verified, and the run it started.")
+        .description("List inbound workflow webhook deliveries: what arrived, whether it verified, and the run it started. Replays never append here; only a verified outcome=ran delivery can be replayed.")
         .argument("[trigger_id]", "Optional webhook trigger name, such as lead-created.")
         .option("--workflow-id <id>", "Filter to deliveries that started a run of this workflow.")
         .option("--outcome <outcome>", "Filter by rejected (sender authentication failed), blocked (authenticated, no run), or ran.")
@@ -14563,7 +14598,7 @@ Run completion:
         limit: options.limit,
     }))))))
         .addCommand(new Command("revisions")
-        .description("Published version history for one workflow, newest first — every save cuts a revision, and this is how you find the one to go back to.")
+        .description("Saved revision history for one workflow, newest first — includes unpublished drafts and published versions; use --include-manifest to inspect either.")
         .argument("[workflow]", "Workflow id, slug, or name.")
         .option("--workflow <workflow>", "Workflow id, slug, or name.")
         .option("--limit <n>", "Maximum revisions to return. Defaults to 50.")
@@ -14760,6 +14795,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
         .argument("<run_id>", "Workflow run UUID returned as data.run.id by workflows call/tail; not the separate provenance run id.")
         .option("--include-bundle", "Include durable recipe bundles in JSON output.")
         .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nWebhook replay: for a webhook-origin run, find its verified delivery with `oxygen workflows webhooks deliveries --workflow-id <workflow-uuid> --outcome ran`, then use `oxygen workflows webhooks replay <delivery-id>`. The replay response and run metadata retain the source delivery/run lineage.\n")
         .action(async (runId, options) => {
         await handleAsyncAction("workflows run", options, async () => prepareWorkflowCliOutput(await requestOxygen("/api/cli/workflows/run", {
             method: "POST",
@@ -15182,9 +15218,10 @@ function scaffoldGraphProject(options) {
         files_written: filesWritten,
         files_skipped: filesSkipped,
         next_steps: [
-            `Edit ${workflowFileName}, then validate it: oxygen workflows lint --file ./${workflowFileName}`,
-            `Install it disabled: oxygen workflows apply --file ./${workflowFileName}`,
-            `Open it: oxygen workflows get ${workflowId} --json`,
+            `Edit ${workflowFileName}, then validate the draft: oxygen workflows lint --file ./${workflowFileName} --phase draft --json`,
+            `Save it without publishing: oxygen workflows apply --file ./${workflowFileName} --draft --json`,
+            `Inspect the saved draft: oxygen workflows revisions ${workflowId} --include-manifest --json`,
+            `Before publishing, validate readiness: oxygen workflows lint --file ./${workflowFileName} --phase publish --json`,
         ],
     };
 }
@@ -15356,8 +15393,21 @@ async function loadWorkflowManifestFromFile(filePath) {
                 ? parsed.manifest
                 : null;
         if (!manifest) {
-            throw new OxygenError("invalid_workflow_manifest", "Workflow JSON must be a manifest or { manifest } object.", {
-                details: { file: filePath },
+            const portable = parsed.kind === "oxygen-workflow-definition"
+                && parsed.definition_version === 1
+                && isRecord(parsed.graph);
+            throw new OxygenError("invalid_workflow_manifest", portable
+                ? `Detected a portable workflow export. Validate it without saving or running anything: oxygen workflows import --file ${filePath} --preflight --json. Workflows lint accepts authored manifests, not import envelopes.`
+                : "Workflow JSON must be a manifest or { manifest } object.", {
+                details: {
+                    file: filePath,
+                    ...(portable
+                        ? {
+                            detected_format: "oxygen-workflow-definition",
+                            next_command: `oxygen workflows import --file ${filePath} --preflight --json`,
+                        }
+                        : {}),
+                },
                 exitCode: 1,
             });
         }

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, } from "./version.js";
+export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION, } from "./version.js";
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, type WorkflowStatusChange, type WorkflowStatusChangeActor, type WorkflowStatusChangeSource, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -1,4 +1,4 @@
-export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, } from "./version.js";
+export { MANAGED_INBOX_MINIMUM_CLI_VERSION, OXYGEN_MINIMUM_CLI_VERSION, OXYGEN_VERSION, SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION, } from "./version.js";
 export { WORKFLOW_TRIGGER_AUTO_PAUSE_METADATA_KEYS, clearWorkflowTriggerAutoPauseMetadata, } from "./workflow-trigger-metadata.js";
 export { WORKFLOW_STATUS_CHANGE_METADATA_KEY, describeWorkflowStatusChange, formatWorkflowStatusChangeTimestamp, parseWorkflowStatusChange, readWorkflowStatusChange, } from "./workflow-status-change.js";
 export * from "./billing.js";

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,3 +1,4 @@
-export declare const OXYGEN_VERSION = "1.739.1";
+export declare const OXYGEN_VERSION = "1.750.4";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
+export declare const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.739.1";
+export const OXYGEN_VERSION = "1.750.4";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:
@@ -39,3 +39,11 @@ export const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 // so it can never exceed npm's newest CLI. (1.298.0 was the prior credits→Stripe
 // contract move.) Do NOT raise the global OXYGEN_MINIMUM_CLI_VERSION for this.
 export const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";
+// Per-surface floor for guarded Plain agent reply + Done. CLI 1.747.0 is the
+// first client that declares --agent, binds the latest customer message and
+// body-authenticated preview token, carries the live agent_done_token into the
+// separate Done confirmation, and never falls through to the retired resolve
+// shape. This floor MUST remain dormant in production until 1.747.0 has been
+// published by the preceding release per OXY-4091; the live feature gate is the
+// rollout boundary that preserves that two-phase ordering.
+export const SUPPORT_AGENT_REPLY_MINIMUM_CLI_VERSION = "1.747.0";

package/node_modules/@oxygen/workflows/dist/graph/expression.d.ts

@@ -1,4 +1,4 @@
-import type { WorkflowCompareOp, WorkflowCondition, WorkflowValueRef } from "./types.js";
+import type { WorkflowCompareOp, WorkflowCondition, WorkflowValueCoercion, WorkflowValueRef } from "./types.js";
 /**
  * The data a v2 run exposes to its value refs.
  *
@@ -22,6 +22,20 @@ export type WorkflowRunScope = {
     contextProfile?: unknown;
     contextAssets?: Record<string, unknown>;
 };
+/** A deterministic authoring/data error; retrying the same revision cannot repair it. */
+export declare class WorkflowValueCoercionError extends Error {
+    readonly coercion: WorkflowValueCoercion;
+    readonly code = "workflow_value_coercion_failed";
+    constructor(coercion: WorkflowValueCoercion);
+}
+/** A direct mapping named data the run does not carry; sending undefined is never intentional. */
+export declare class WorkflowValueRefUnresolvedError extends Error {
+    readonly path: string;
+    readonly code = "workflow_value_ref_unresolved";
+    constructor(path: string);
+}
+/** Apply one explicit scalar conversion without lossy truthiness or truncation. */
+export declare function coerceWorkflowValue(value: unknown, coercion: WorkflowValueCoercion): string | number | boolean;
 /** The roots a `ref` path may start from. Anything else is not a scope path. */
 export declare const SCOPE_PATH_ROOTS: ReadonlySet<string>;
 export declare const WORKFLOW_COMPARE_OPS: ReadonlySet<WorkflowCompareOp>;
@@ -40,6 +54,8 @@ export declare const UNARY_COMPARE_OPS: ReadonlySet<WorkflowCompareOp>;
  * typo surfaces in lint rather than as a silently empty value at run time.
  */
 export declare function parseScopePath(path: string): string[] | null;
+/** Canonical path formatter: dots for simple keys, JSON brackets for every other key. */
+export declare function formatScopePath(segments: readonly string[]): string | null;
 /** Resolve a dotted (+ `[n]`) scope path. Missing or malformed → undefined. */
 export declare function resolvePath(path: string, scope: WorkflowRunScope): unknown;
 /**
@@ -49,6 +65,16 @@ export declare function resolvePath(path: string, scope: WorkflowRunScope): unkn
  */
 export declare function renderTemplate(template: string, scope: WorkflowRunScope): string;
 export declare function resolveValueRef(ref: WorkflowValueRef, scope: WorkflowRunScope): unknown;
+/**
+ * Resolve a binding that is about to cross an execution boundary.
+ *
+ * Conditions and optional control-flow refs deliberately keep total lookup
+ * semantics: a missing path is `undefined`, so `is_empty` remains useful. Tool
+ * requests are different — silently handing `undefined` to a provider makes a
+ * stale mapping look like a provider bug. Call this stricter adapter at that
+ * boundary so the failure names the mapped path before any provider executes.
+ */
+export declare function resolveRequiredValueRef(ref: WorkflowValueRef, scope: WorkflowRunScope): unknown;
 export declare function evaluateCondition(condition: WorkflowCondition, scope: WorkflowRunScope): boolean;
 /**
  * Compile a `matches` pattern, or return null when it is unsafe or invalid.
@@ -76,3 +102,5 @@ export declare function compileConditionPattern(pattern: string): RegExp | null;
  * with the manifest's declared node ids.
  */
 export declare function referencedNodeIds(ref: WorkflowValueRef | WorkflowCondition): string[];
+/** Exact rooted scope paths a ref/condition can read, excluding ambiguous bare formula names. */
+export declare function referencedScopePaths(ref: WorkflowValueRef | WorkflowCondition): string[];