@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/local-module-loader.d.ts

@@ -0,0 +1,4 @@
+import { type RecipeDefinition } from "@oxygen/recipe-sdk";
+export declare function loadRecipeFromBundle(bundle: string, filePath: string): Promise<RecipeDefinition>;
+export declare function importJavaScriptWorkflowModule(absolutePath: string, source: string): Promise<Record<string, unknown>>;
+export declare function importTranspiledWorkflowModule(absolutePath: string, source: string): Promise<Record<string, unknown>>;

package/dist/local-module-loader.js

@@ -0,0 +1,156 @@
+import { isRecipeDefinition } from "@oxygen/recipe-sdk";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+// Escape Next static analysis (the CLI is bundled by tsc, but mirror the
+// worker's escape so both load identically).
+// skipcq: JS-R1003 — intentional dynamic-import escape mirrored from the worker; not arbitrary code execution
+const dynamicRecipeImport = new Function("specifier", "return import(specifier);");
+async function importRecipeModule(specifier) {
+    try {
+        return await dynamicRecipeImport(specifier);
+    }
+    catch (error) {
+        if (error instanceof TypeError && error.message.includes("dynamic import callback")) {
+            return await import(specifier);
+        }
+        throw error;
+    }
+}
+export async function loadRecipeFromBundle(bundle, filePath) {
+    const dir = mkdtempSync(`${tmpdir()}/oxygen-recipe-`);
+    const compiledPath = `${dir}/recipe.mjs`;
+    writeFileSync(compiledPath, bundle, "utf8");
+    try {
+        const url = pathToFileURL(compiledPath);
+        url.searchParams.set("v", createHash("sha256").update(bundle).digest("hex").slice(0, 16));
+        const mod = await importRecipeModule(url.href);
+        const candidate = mod.default ?? mod.recipe ?? mod.workflow;
+        if (!isRecipeDefinition(candidate)) {
+            throw new OxygenError("invalid_workflow_file", "Recipe module must export a defineRecipe() result as default.", {
+                details: { file: filePath },
+                exitCode: 1,
+            });
+        }
+        return candidate;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export async function importJavaScriptWorkflowModule(absolutePath, source) {
+    const url = pathToFileURL(absolutePath);
+    url.searchParams.set("v", createHash("sha256").update(source).digest("hex").slice(0, 16));
+    return await import(url.href);
+}
+export async function importTranspiledWorkflowModule(absolutePath, source) {
+    if (/\bfrom\s+["']\.\.?\//.test(source) || /\bimport\s*\(\s*["']\.\.?\//.test(source)) {
+        throw new OxygenError("unsupported_workflow_file", "TypeScript workflow files cannot use relative imports in workflow modules.", {
+            details: { file: absolutePath },
+            exitCode: 1,
+        });
+    }
+    const ts = await import("typescript");
+    const transpiled = ts.transpileModule(source, {
+        fileName: absolutePath,
+        compilerOptions: {
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ES2022,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            esModuleInterop: true,
+        },
+    }).outputText;
+    const dir = mkdtempSync(`${tmpdir()}/oxygen-workflow-`);
+    const workflowsUrl = await resolveWorkflowRuntimeModuleUrl(dir);
+    const rewritten = transpiled
+        .replaceAll("from \"@oxygen/workflows\"", `from "${workflowsUrl}"`)
+        .replaceAll("from '@oxygen/workflows'", `from "${workflowsUrl}"`);
+    const compiledPath = `${dir}/workflow.mjs`;
+    writeFileSync(compiledPath, rewritten, "utf8");
+    try {
+        return await importJavaScriptWorkflowModule(compiledPath, rewritten);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function resolveWorkflowRuntimeModuleUrl(tempDir) {
+    try {
+        return await import.meta.resolve("@oxygen/workflows");
+    }
+    catch {
+        const shimPath = `${tempDir}/oxygen-workflows-shim.mjs`;
+        writeFileSync(shimPath, workflowRuntimeShimSource(), "utf8");
+        return pathToFileURL(shimPath).href;
+    }
+}
+function workflowRuntimeShimSource() {
+    return `
+export function defineWorkflow(input) {
+  return {
+    __oxygen_workflow_definition: true,
+    id: input.id,
+    name: input.name,
+    ...(input.status ? { status: input.status } : {}),
+    ...(input.specification ? { specification: input.specification } : {}),
+    ...(input.trigger ? { trigger: input.trigger } : {}),
+    ...(input.inputSchema ? { inputSchema: input.inputSchema } : {}),
+    steps: input.steps,
+  };
+}
+export function apiTrigger(input = {}) {
+  return { type: "api", ...(input.status ? { status: input.status } : {}) };
+}
+export function webhookTrigger(input) {
+  return {
+    type: "webhook",
+    trigger_id: input.id,
+    ...(input.name !== undefined ? { trigger_name: input.name } : {}),
+    secret_required: input.secret ?? true,
+    ...(input.idempotencyKeyPath !== undefined ? { idempotency_key_path: input.idempotencyKeyPath } : {}),
+    ...(input.status ? { status: input.status } : {}),
+  };
+}
+export function cronTrigger(input) {
+  return {
+    type: "cron",
+    cron: input.cron,
+    ...(input.timezone !== undefined ? { timezone: input.timezone } : {}),
+    ...(input.status ? { status: input.status } : {}),
+  };
+}
+export function eventTrigger(input) {
+  return {
+    type: "event",
+    source: input.source,
+    event: input.event,
+    ...(input.filters ? { filters: input.filters } : {}),
+    ...(input.idempotencyKeyPath !== undefined ? { idempotency_key_path: input.idempotencyKeyPath } : {}),
+    ...(input.status ? { status: input.status } : {}),
+  };
+}
+export function transformStep(input) {
+  return {
+    __oxygen_workflow_step: true,
+    kind: "transform",
+    id: input.id,
+    ...(input.description ? { description: input.description } : {}),
+    run: input.run,
+  };
+}
+export function toolStep(input) {
+  return {
+    __oxygen_workflow_step: true,
+    kind: "tool",
+    id: input.id,
+    ...(input.description ? { description: input.description } : {}),
+    tool: input.tool,
+    ...(input.effect ? { effect: input.effect } : {}),
+    ...(input.mode ? { mode: input.mode } : {}),
+    payload: input.payload,
+  };
+}
+`;
+}

package/dist/visual-commands.js

@@ -1,3 +1,4 @@
+import { Option } from "commander";
 import { createHash } from "node:crypto";
 import { readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -31,16 +32,19 @@ export function registerVisualCommands(program, handle) {
         writeFileSync(options.out, bytes, { flag: "wx", mode: 0o600 });
         return { path: resolve(options.out), ...data.file };
     }));
-    visuals.command("render-preview").description("Preview rendering without starting paid compute.")
+    visuals.command("render-preview").description("Preview rendering without starting compute; rendering is free.")
         .requiredOption("--source-file-ids <ids>", "Comma-separated HTML file UUIDs in page order.")
         .option("--width <pixels>", "CSS pixel width.", "1080").option("--height <pixels>", "CSS pixel height.", "1350")
         .option("--scale <1|2>", "PNG scale.", "1").option("--formats <png,pdf>", "Output formats.", "png")
         .option("--json", "Print a JSON envelope.")
         .action((options) => handle("visuals render preview", options, () => requestOxygen("/api/cli/visuals/renders", { method: "POST", body: { source_file_ids: options.sourceFileIds.split(",").map((s) => s.trim()), width: Number(options.width), height: Number(options.height), scale: Number(options.scale), formats: options.formats.split(",") } })));
-    visuals.command("render-start <render-id>").description("Approve an exact preview and enqueue one idempotent render job.")
-        .requiredOption("--scope-hash <hash>", "Exact preview scope hash.").requiredOption("--max-credits <credits>", "Approved ceiling from preview.")
-        .requiredOption("--approved", "Authorize this exact render.").option("--json", "Print a JSON envelope.")
-        .action((id, options) => handle("visuals render start", options, () => requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`, { method: "POST", body: { scope_hash: options.scopeHash, max_credits: Number(options.maxCredits), approved: options.approved } })));
+    visuals.command("render-start <render-id>").description("Start an exact preview as one idempotent render job; rendering is free.")
+        .requiredOption("--scope-hash <hash>", "Exact preview scope hash.")
+        // Rendering became free on 2026-10-14; the approval flags it needed are retired.
+        .addOption(new Option("--max-credits <credits>", "Deprecated: rendering is free. Still accepted so older scripts keep running.").hideHelp())
+        .addOption(new Option("--approved", "Deprecated: rendering is free. Still accepted so older scripts keep running.").hideHelp())
+        .option("--json", "Print a JSON envelope.")
+        .action((id, options) => handle("visuals render start", options, () => requestOxygen(`/api/cli/visuals/renders/${encodeURIComponent(id)}`, { method: "POST", body: { scope_hash: options.scopeHash } })));
     visuals.command("render-get <render-id>").description("Read render state and output downloads; optionally wait for a terminal state.")
         .option("--wait", "Poll every 2 seconds until completed, failed, cancelled or effect_unknown; starts no render.")
         .option("--timeout-seconds <n>", "Maximum wait with --wait, from 1 to 600 seconds. Defaults to 180.")

package/node_modules/@oxygen/cli-ugc/dist/commands.js

@@ -141,7 +141,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
     }));
     group("analytics")
         .command("get")
-        .description("Read UGC analytics in the active workspace. Read-only. The brand workspace sees every creator; a creator workspace only ever gets its own row, with or without --participation-id.")
+        .description("Read UGC analytics in the active workspace. Read-only. Find available program IDs with `ugc programs list --json`. The brand workspace sees every creator; a creator workspace only ever gets its own row, with or without --participation-id.")
         .requiredOption("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
         .option("--post-cursor <cursor>", "Next post_performance page from next_post_cursor; totals still cover all enrolled posts.")
@@ -1035,7 +1035,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             action: "sponsorship_preview",
             command: "sponsorship preview",
-            description: "Preview sponsoring creators who already joined, as a signed-in master admin: funding is card (seat plus 10,000-credit grant) or credits (one LinkedIn reservation per creator). Org API keys cannot quote. To sponsor creators who have not joined yet, invite them with creators invite --sponsor.",
+            description: "Preview card or credit sponsorship costs as a signed-in master admin; may apply due plan grants or expiry. Card funds a seat plus 10,000 credits; credits reserve one LinkedIn account per joined creator. Org API keys cannot quote. Before creators join, use creators invite --sponsor.",
             fields: [
                 {
                     name: "program_id",

package/node_modules/@oxygen/shared/dist/agent-session-schedule.d.ts

@@ -0,0 +1,36 @@
+/** The original kind, and the default when `kind` is absent. */
+export type AgentSessionIntervalSchedule = {
+    kind?: "interval";
+    interval_minutes: number;
+    min_interval_minutes: number;
+    max_interval_minutes: number;
+};
+/** Wakes at each cron time in `timezone`; the session cannot move its own next wake. */
+export type AgentSessionCronSchedule = {
+    kind: "cron";
+    cron: string;
+    timezone: string;
+};
+export type AgentSessionSchedule = AgentSessionIntervalSchedule | AgentSessionCronSchedule;
+/** The fastest any session may wake, whichever kind of schedule it has. */
+export declare const AGENT_SESSION_MIN_INTERVAL_MINUTES = 5;
+export declare function agentSessionScheduleKind(schedule: AgentSessionSchedule): "interval" | "cron";
+/**
+ * What is wrong with a schedule, or null. A cron expression is checked for
+ * syntax and its zone for existence here; whether it fires, and no more often
+ * than every five minutes, needs the scheduler and is checked by the host.
+ */
+export declare function agentSessionScheduleProblem(schedule: unknown): string | null;
+/** The schedule in words, a cron one with its zone: "Weekdays at 09:00 (Europe/Berlin)". */
+export declare function describeAgentSessionSchedule(schedule: AgentSessionSchedule): string;
+export type NextCronRunAfter = (input: {
+    cron: string;
+    timezone: string;
+    after: Date;
+}) => Date;
+/**
+ * When a cron session next wakes after `after`, from the host's scheduler; null
+ * for an interval session, whose next wake the store counts on the database
+ * clock. Missed cron times are skipped, never replayed.
+ */
+export declare function nextAgentSessionCronWake(schedule: AgentSessionSchedule, after: Date, nextCronRunAfter: NextCronRunAfter): Date | null;

package/node_modules/@oxygen/shared/dist/agent-session-schedule.js

@@ -0,0 +1,69 @@
+// When an ongoing Agent session wakes (ADR 0011 sessions; ADR 0032 routines):
+// every N minutes, or at the times of a cron expression in an IANA time zone.
+//
+// One owner for the shape, its validation and its words, because the session
+// store, the web, the worker and a teammate's routine card all read it. Where
+// the next cron time falls is the Workflows scheduler's answer
+// (`nextCronRunAfter`), which this layer cannot import: hosts pass it in.
+import { humanizeCronSchedule, isCronSyntax } from "./schedule-label.js";
+import { isValidTimeZone } from "./zoned-time.js";
+/** The fastest any session may wake, whichever kind of schedule it has. */
+export const AGENT_SESSION_MIN_INTERVAL_MINUTES = 5;
+const MAX_INTERVAL_MINUTES = 525_600;
+const INTERVAL_FIELDS = ["interval_minutes", "min_interval_minutes", "max_interval_minutes"];
+export function agentSessionScheduleKind(schedule) {
+    return schedule.kind === "cron" ? "cron" : "interval";
+}
+/**
+ * What is wrong with a schedule, or null. A cron expression is checked for
+ * syntax and its zone for existence here; whether it fires, and no more often
+ * than every five minutes, needs the scheduler and is checked by the host.
+ */
+export function agentSessionScheduleProblem(schedule) {
+    if (!schedule || typeof schedule !== "object" || Array.isArray(schedule))
+        return "Set a schedule.";
+    const value = schedule;
+    if (value.kind === "cron") {
+        if (INTERVAL_FIELDS.some((key) => value[key] !== undefined)) {
+            return "A cron schedule wakes at its cron times; leave out the interval fields.";
+        }
+        if (typeof value.cron !== "string" || !isCronSyntax(value.cron))
+            return "Use a five-field cron expression, e.g. \"0 9 * * 1-5\".";
+        if (typeof value.timezone !== "string" || !isValidTimeZone(value.timezone))
+            return "Use an IANA time zone for the cron schedule, e.g. Europe/Berlin.";
+        return null;
+    }
+    if (value.kind !== undefined && value.kind !== "interval")
+        return "Choose an interval or a cron schedule.";
+    if (value.cron !== undefined || value.timezone !== undefined)
+        return "Set kind to cron to wake at cron times in a time zone.";
+    const [interval, min, max] = INTERVAL_FIELDS.map((key) => value[key]);
+    const numbers = [interval, min, max].every((field) => typeof field === "number" && Number.isFinite(field));
+    if (!numbers || min < AGENT_SESSION_MIN_INTERVAL_MINUTES || max < min
+        || interval < min || interval > max || max > MAX_INTERVAL_MINUTES) {
+        return "The check interval must fit approved bounds (at least five minutes).";
+    }
+    return null;
+}
+function everyMinutes(minutes) {
+    if (minutes % 1_440 === 0)
+        return minutes === 1_440 ? "Every day" : `Every ${minutes / 1_440} days`;
+    if (minutes % 60 === 0)
+        return minutes === 60 ? "Every hour" : `Every ${minutes / 60} hours`;
+    return `Every ${minutes} minutes`;
+}
+/** The schedule in words, a cron one with its zone: "Weekdays at 09:00 (Europe/Berlin)". */
+export function describeAgentSessionSchedule(schedule) {
+    if (schedule.kind === "cron") {
+        return `${humanizeCronSchedule(schedule.cron) ?? `Cron ${schedule.cron.trim()}`} (${schedule.timezone})`;
+    }
+    return everyMinutes(schedule.interval_minutes);
+}
+/**
+ * When a cron session next wakes after `after`, from the host's scheduler; null
+ * for an interval session, whose next wake the store counts on the database
+ * clock. Missed cron times are skipped, never replayed.
+ */
+export function nextAgentSessionCronWake(schedule, after, nextCronRunAfter) {
+    return schedule.kind === "cron" ? nextCronRunAfter({ cron: schedule.cron, timezone: schedule.timezone, after }) : null;
+}

package/node_modules/@oxygen/shared/dist/agent-sessions.d.ts

@@ -1,3 +1,4 @@
+import { type AgentSessionSchedule } from "./agent-session-schedule.js";
 export type AgentSessionStatus = "draft" | "active" | "paused" | "budget_wait" | "completed" | "archived";
 export type AgentSessionResources = {
     sequences: string[];
@@ -15,11 +16,7 @@ export type AgentSessionConfig = {
     template: string;
     resources: AgentSessionResources;
     actions: string[];
-    schedule: {
-        interval_minutes: number;
-        min_interval_minutes: number;
-        max_interval_minutes: number;
-    };
+    schedule: AgentSessionSchedule;
     budget: {
         per_run_credits: number;
         daily_credits: number;
@@ -27,7 +24,19 @@ export type AgentSessionConfig = {
     };
     ends_at?: string | undefined;
     events: string[];
+    /**
+     * A teammate routine (ADR 0032): set up from its creator's private chat with
+     * the teammate, which its reports post into. Only the creator may start,
+     * change or message it; anyone may pause it.
+     */
+    teammate_routine?: AgentSessionTeammateRoutine | undefined;
+};
+export type AgentSessionTeammateRoutine = {
+    chat_id: string;
+    proposal_id?: string | undefined;
 };
+/** The routine marker of a session's settings, or null for a general session. */
+export declare function agentSessionTeammateRoutine(config: Pick<AgentSessionConfig, "teammate_routine">): AgentSessionTeammateRoutine | null;
 export declare function agentSessionsEnabled(env?: Record<string, string | undefined>): boolean;
 export declare function agentSessionsAvailableTo(env: Record<string, string | undefined>, viewer: {
     email: string | null | undefined;

package/node_modules/@oxygen/shared/dist/agent-sessions.js

@@ -1,6 +1,12 @@
 import { isStaffEmail } from "./staff.js";
 import { OxygenError } from "./cli-result.js";
 import { WORKSPACE_EVENT_CATALOG } from "./workspace-event-catalog.js";
+import { agentSessionScheduleProblem } from "./agent-session-schedule.js";
+/** The routine marker of a session's settings, or null for a general session. */
+export function agentSessionTeammateRoutine(config) {
+    const marker = config.teammate_routine;
+    return marker && typeof marker.chat_id === "string" ? marker : null;
+}
 export function agentSessionsEnabled(env = process.env) {
     return env.OXYGEN_DEPLOY_ENV === "selfhost-dev" && env.OXYGEN_AGENT_SESSIONS_ENABLED === "staff" && env.OXYGEN_AGENTS_ENABLED?.trim().toLowerCase() === "true";
 }
@@ -109,9 +115,14 @@ export function validateAgentSessionConfig(config, requireResources = true) {
         fail("Set positive per-run and rolling daily caps; daily must cover one run and per-run cannot exceed 25,000 credits.");
     if (lifetime !== undefined && (!Number.isFinite(lifetime) || lifetime < perRun))
         fail("The lifetime cap must cover one run.");
-    const { interval_minutes: interval, min_interval_minutes: min, max_interval_minutes: max } = config.schedule;
-    if (![interval, min, max].every(Number.isFinite) || min < 5 || max < min || interval < min || interval > max || max > 525600)
-        fail("The check interval must fit approved bounds (at least five minutes).");
+    const scheduleProblem = agentSessionScheduleProblem(config.schedule);
+    if (scheduleProblem)
+        fail(scheduleProblem);
+    const routine = config.teammate_routine;
+    if (routine !== undefined && (!routine || typeof routine.chat_id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(routine.chat_id)
+        || (routine.proposal_id !== undefined && (typeof routine.proposal_id !== "string" || !routine.proposal_id.trim() || routine.proposal_id.length > 64)))) {
+        fail("An Oxygent routine names the chat it reports into by its session ID.");
+    }
     if (config.ends_at && !Number.isFinite(Date.parse(config.ends_at)))
         fail("Use an ISO date for the end time.");
     if (config.actions.some(name => !AGENT_SESSION_ADAPTERS[name] || AGENT_SESSION_ADAPTERS[name].read))