@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/agent.js

@@ -0,0 +1,274 @@
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { readPositiveNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE } from "@oxygen/shared/plan-band";
+import { Command } from "commander";
+const AGENT_MODEL_POLICY_HELP = "Model policy JSON: level low (Fast), medium (Balanced, default), or high (Max); credential_mode managed or organization_byok.";
+const AGENT_TOOL_POLICY_HELP = "Tool policy JSON. Effects: read, internal_write, paid, external_write. Ask-before-changes preset: {\"mode\":\"scoped\",\"rules\":[{\"decision\":\"allow\",\"effect\":\"read\"},{\"decision\":\"ask\",\"effect\":\"internal_write\"},{\"decision\":\"ask\",\"effect\":\"paid\"},{\"decision\":\"ask\",\"effect\":\"external_write\"}]}. Full mode requires --confirm-full-access.";
+const WEBHOOK_TRIGGER_RATE_HELP = `${PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE.free.toLocaleString("en-US")}–${PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE["1999"].toLocaleString("en-US")} deliveries a minute by plan size, per trigger and sender IP; 429 returns Retry-After`;
+export function registerAgentFamily(program, handleAsyncAction) {
+    // The Agents primitive's roster surface (ADR 0011): governed workspace agents
+    // that run inside the workspace as approval-gated, observable runs. Lists only
+    // shipped agents — no placeholders; user-defined custom agents arrive with the
+    // unified runtime envelope (create/update land then). (Distinct from
+    // `oxygen knowledge agent`, which configures the AI Knowledge Agent itself.)
+    program
+        .command("agent")
+        .description("Agents: the programmable Workspace Agent, custom Agents, and built-in specialists. Publish versioned instructions and policies, start durable chats/runs, inspect every event, and control approvals. Web: /agents.")
+        .addCommand(new Command("list")
+        .description("List the Workspace Agent and built-in specialists with state and recent run history.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("agent list", options, () => requestOxygen("/api/cli/agent"));
+    }))
+        .addCommand(new Command("get")
+        .description("Show one agent — the Workspace Agent, a specialist, or a custom agent — with its active version and recent runs.")
+        .argument("<slug>", "Agent slug: workspace, a specialist (inbox-reply-drafts, meeting-notetaker, knowledge-synthesis), or a custom agent slug (from `oxygen agent create`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent get", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}`));
+    }))
+        .addCommand(new Command("enable")
+        .description("Enable a workspace or specialist agent so it resumes its governed runs.")
+        .argument("<slug>", "Specialist slug: inbox-reply-drafts, meeting-notetaker, or knowledge-synthesis.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent enable", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/enable`, { method: "POST" }));
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable a workspace or specialist agent so it stops new runs on the next worker tick.")
+        .argument("<slug>", "Specialist slug: inbox-reply-drafts, meeting-notetaker, or knowledge-synthesis.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent disable", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/disable`, { method: "POST" }));
+    }))
+        .addCommand(new Command("runs")
+        .description("List recent runs across all agents (or one via <slug>), newest first.")
+        .argument("[slug]", "Optional agent slug to filter to one agent.")
+        .option("--limit <n>", "Maximum runs to return (1-100). Defaults to 25.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent runs", options, () => {
+            const params = new URLSearchParams();
+            const target = readOption(slug);
+            const limit = readPositiveInt(options.limit);
+            if (target)
+                params.set("slug", target);
+            if (limit)
+                params.set("limit", String(limit));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/agent/runs${suffix}`);
+        });
+    }))
+        .addCommand(new Command("set")
+        .description("Publish an immutable version (reconfigure) for a runtime agent: the Workspace Agent or a custom agent.")
+        .argument("<slug>", "workspace, or a custom agent slug (from `oxygen agent create`).")
+        .requiredOption("--instructions <text>", "Workspace Agent instructions for this version.")
+        .option("--model-policy-json <json>", AGENT_MODEL_POLICY_HELP)
+        .option("--tool-policy-json <json>", AGENT_TOOL_POLICY_HELP)
+        .option("--context-policy-json <json>", "Context policy JSON: on_demand, prefetch, or grounded (seeds the run from the workspace knowledge wiki); optional resolve_args and file_ids.")
+        .option("--skills <csv>", "Comma-separated product skill slugs snapshotted into this immutable version.")
+        .option("--sandbox-policy-json <json>", "Sandbox policy JSON.")
+        .option("--limits-json <json>", "Optional limits JSON; platform hard ceilings still apply.")
+        .option("--confirm-full-access", "Acknowledge standing full catalog access when the policy mode is full.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent set", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}`, {
+            method: "PATCH",
+            body: {
+                instructions: options.instructions,
+                ...(options.modelPolicyJson ? { model_policy: parseJsonObject(options.modelPolicyJson) } : {}),
+                ...(options.toolPolicyJson ? { tool_policy: parseJsonObject(options.toolPolicyJson) } : {}),
+                ...(options.contextPolicyJson ? { context_policy: parseJsonObject(options.contextPolicyJson) } : {}),
+                ...(options.skills ? { skill_slugs: options.skills.split(",").map((value) => value.trim()).filter(Boolean) } : {}),
+                ...(options.sandboxPolicyJson ? { sandbox_policy: parseJsonObject(options.sandboxPolicyJson) } : {}),
+                ...(options.limitsJson ? { limits: parseJsonObject(options.limitsJson) } : {}),
+                confirm_full_access: options.confirmFullAccess === true,
+            },
+        }));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a custom Agent and publish its first immutable version. This internal configuration write starts no chat/run and spends no credits.")
+        .argument("<slug>", "User-minted agent slug: a lowercase letter then letters, digits, or hyphens (2-49 chars).")
+        .requiredOption("--name <name>", "Display name for the agent.")
+        .requiredOption("--instructions <text>", "Durable standing instructions for the first immutable version.")
+        .option("--description <text>", "Optional one-line description of the agent's job.")
+        .option("--model-policy-json <json>", AGENT_MODEL_POLICY_HELP)
+        .option("--tool-policy-json <json>", AGENT_TOOL_POLICY_HELP)
+        .option("--context-policy-json <json>", "Context policy JSON: on_demand, prefetch, or grounded (seeds the run from the workspace knowledge wiki); optional resolve_args and file_ids.")
+        .option("--skills <csv>", "Comma-separated product skill slugs snapshotted into this immutable version.")
+        .option("--sandbox-policy-json <json>", "Sandbox policy JSON.")
+        .option("--limits-json <json>", "Optional limits JSON; platform hard ceilings still apply.")
+        .option("--confirm-full-access", "Acknowledge standing full catalog access when the policy mode is full.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent create", options, () => requestOxygen("/api/cli/agent/create", {
+            method: "POST",
+            body: {
+                slug,
+                name: options.name,
+                instructions: options.instructions,
+                ...(options.description ? { description: options.description } : {}),
+                ...(options.modelPolicyJson ? { model_policy: parseJsonObject(options.modelPolicyJson) } : {}),
+                ...(options.toolPolicyJson ? { tool_policy: parseJsonObject(options.toolPolicyJson) } : {}),
+                ...(options.contextPolicyJson ? { context_policy: parseJsonObject(options.contextPolicyJson) } : {}),
+                ...(options.skills ? { skill_slugs: options.skills.split(",").map((value) => value.trim()).filter(Boolean) } : {}),
+                ...(options.sandboxPolicyJson ? { sandbox_policy: parseJsonObject(options.sandboxPolicyJson) } : {}),
+                ...(options.limitsJson ? { limits: parseJsonObject(options.limitsJson) } : {}),
+                confirm_full_access: options.confirmFullAccess === true,
+            },
+        }));
+    }))
+        .addCommand(new Command("custom")
+        .description("List the org's user-defined custom agents (distinct from `agent list`, which shows the built-in roster).")
+        .option("--tag <tag>", "Only custom agents carrying this workspace tag.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("agent custom", options, () => requestOxygen(`/api/cli/agent/custom${options.tag ? `?tag=${encodeURIComponent(options.tag)}` : ""}`));
+    }))
+        .addCommand(new Command("delete")
+        .description("Archive a custom agent (soft delete): its triggers stop firing and it leaves the roster; versions/runs are preserved.")
+        .argument("<slug>", "The custom agent slug to archive.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent delete", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}`, { method: "DELETE" }));
+    }))
+        .addCommand(new Command("run")
+        .description("Start a durable chat/run for the Workspace Agent or a custom Agent on the Fly worker.")
+        .argument("<slug>", "workspace, or a custom Agent slug from `oxygen agent custom`.")
+        .option("--goal <text>", "Natural-language goal.")
+        .option("--input-json <json>", "Structured run input instead of --goal.")
+        .option("--idempotency-key <key>", "Deduplicate retries of the same source event.")
+        .option("--thread-id <id>", "Continue an existing persistent Agent thread.")
+        .option("--thread-mode <isolated|persistent>", "Create a persistent thread for this run. Defaults to isolated.")
+        .option("--file-ids <csv>", "Comma-separated workspace file UUIDs attached to context and eligible for sandbox input.")
+        .requiredOption("--max-credits <credits>", "Hard credit ceiling for this run.")
+        .requiredOption("--approved", "Explicitly approve managed inference up to --max-credits.")
+        .option("--approve-above-default", "Also approve a --max-credits above your default Agent run ceiling (`oxygen limits show`: spend_safety_defaults.agent_run_max_total_credits), for this run only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent run", options, () => {
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxCredits === undefined)
+                throw new OxygenError("invalid_request", "--max-credits must be positive.", { exitCode: 2 });
+            return requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/runs`, {
+                method: "POST",
+                body: {
+                    ...(options.goal ? { goal: options.goal } : {}),
+                    ...(options.inputJson ? { input: parseJsonObject(options.inputJson) } : {}),
+                    ...(options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}),
+                    ...(options.threadId ? { thread_id: options.threadId } : {}),
+                    thread_mode: options.threadMode ?? "isolated",
+                    ...(options.fileIds ? { file_ids: options.fileIds.split(",").map((value) => value.trim()).filter(Boolean) } : {}),
+                    max_credits: maxCredits,
+                    approved: options.approved === true,
+                    ...(options.approveAboveDefault ? { approve_above_default: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("run-get")
+        .description("Inspect one Workspace or custom Agent run and its append-only event ledger.")
+        .argument("<slug>", "workspace, or a custom Agent slug from `oxygen agent custom`.")
+        .argument("<run-id>", "Agent run id.")
+        .option("--after-seq <n>", "Return events after this sequence number.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, runId, options) => {
+        await handleAsyncAction("agent run get", options, () => {
+            const params = new URLSearchParams();
+            if (options.afterSeq)
+                params.set("after_seq", options.afterSeq);
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/runs/${encodeURIComponent(runId)}${suffix}`);
+        });
+    }))
+        .addCommand(new Command("cancel")
+        .description("Request cancellation of an active Workspace or custom Agent run.")
+        .argument("<slug>", "workspace, or a custom Agent slug from `oxygen agent custom`.")
+        .argument("<run-id>", "Agent run id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, runId, options) => {
+        await handleAsyncAction("agent run cancel", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" }));
+    }))
+        .addCommand(new Command("approval-decide")
+        .description("Approve or reject one pending Workspace or custom Agent tool call, then resume its durable run.")
+        .argument("<slug>", "workspace, or a custom Agent slug from `oxygen agent custom`.")
+        .argument("<run-id>", "Agent run id.")
+        .argument("<approval-id>", "Approval id from the run event ledger.")
+        .requiredOption("--decision <approved|rejected>", "Decision.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, runId, approvalId, options) => {
+        await handleAsyncAction("agent approval decide", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/runs/${encodeURIComponent(runId)}/approvals/${encodeURIComponent(approvalId)}`, { method: "POST", body: { decision: options.decision } }));
+    }))
+        .addCommand(new Command("trigger-create")
+        .description(`Create a cron, internal event, or signed-webhook trigger for the Workspace Agent. A webhook trigger returns its URL, its secret once, and rate_limit: ${WEBHOOK_TRIGGER_RATE_HELP}.`)
+        .argument("<slug>", "Currently: workspace.")
+        .requiredOption("--type <cron|event|webhook>", "Trigger type.")
+        .requiredOption("--instruction <text>", "Goal template run for each delivery.")
+        .option("--cron <expression>", "Five-field cron expression for cron triggers.")
+        .option("--timezone <iana>", "IANA timezone. Defaults to UTC.")
+        .option("--event-source <source>", "Internal workflow-event source for event triggers.")
+        .option("--event-type <event>", "Internal workflow-event type for event triggers.")
+        .option("--thread-mode <isolated|persistent>", "Reuse a bounded thread across deliveries. Defaults to isolated.")
+        .requiredOption("--max-credits <credits>", "Standing per-delivery credit ceiling.")
+        .requiredOption("--approved", "Authorize each trigger delivery up to --max-credits.")
+        .option("--approve-above-default", "Also approve a per-delivery --max-credits above your default Agent run ceiling (`oxygen limits show`: spend_safety_defaults.agent_run_max_total_credits), for every delivery of this trigger.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent trigger create", options, () => {
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxCredits === undefined)
+                throw new OxygenError("invalid_request", "--max-credits must be positive.", { exitCode: 2 });
+            return requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/triggers`, { method: "POST", body: {
+                    type: options.type, instruction_template: options.instruction,
+                    ...(options.cron ? { cron_expression: options.cron } : {}),
+                    ...(options.timezone ? { timezone: options.timezone } : {}),
+                    ...(options.eventSource ? { event_source: options.eventSource } : {}),
+                    ...(options.eventType ? { event_type: options.eventType } : {}),
+                    thread_mode: options.threadMode ?? "isolated",
+                    max_credits: maxCredits,
+                    approved: options.approved === true,
+                    ...(options.approveAboveDefault ? { approve_above_default: true } : {}),
+                } });
+        });
+    }))
+        .addCommand(new Command("triggers")
+        .description("List Workspace Agent cron, internal event, and webhook triggers. A legacy cron held to the plan minimum includes slowed_to_plan_minimum and its next run time.")
+        .argument("<slug>", "Currently: workspace.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        await handleAsyncAction("agent triggers", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/triggers`));
+    }))
+        .addCommand(new Command("trigger-set")
+        .description("Activate, pause, or archive one Workspace Agent trigger.")
+        .argument("<slug>", "Currently: workspace.")
+        .argument("<trigger-id>", "Agent trigger id.")
+        .requiredOption("--status <active|paused|archived>", "New trigger status.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, triggerId, options) => {
+        await handleAsyncAction("agent trigger set", options, () => requestOxygen(`/api/cli/agent/${encodeURIComponent(slug)}/triggers/${encodeURIComponent(triggerId)}`, { method: "PATCH", body: { status: options.status } }));
+    }))
+        .addCommand(new Command("file-create")
+        .description("Store a tenant-owned text file for Agent context and sandbox input.")
+        .requiredOption("--name <name>", "Workspace filename.")
+        .requiredOption("--text <text>", "Inline text content (max 1.5 MB).")
+        .option("--mime-type <type>", "MIME type. Defaults to text/plain.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("agent file create", options, () => requestOxygen("/api/cli/agent/files", {
+            method: "POST", body: { name: options.name, text: options.text, mime_type: options.mimeType ?? "text/plain" },
+        }));
+    }))
+        .addCommand(new Command("files")
+        .description("List tenant-owned Agent context files.")
+        .option("--limit <n>", "Maximum files (1-500).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("agent files", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen(`/api/cli/agent/files${limit ? `?limit=${limit}` : ""}`);
+        });
+    }));
+}

package/dist/commands/api-keys.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerApiKeysFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/api-keys.js

@@ -0,0 +1,77 @@
+import { readPositiveInt } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+function buildApiKeyCreateBody(options) {
+    const body = {};
+    const name = readOption(options.name);
+    if (name)
+        body.name = name;
+    const expiresAt = resolveApiKeyExpiresAt(options);
+    if (expiresAt)
+        body.expires_at = expiresAt;
+    return body;
+}
+function resolveApiKeyExpiresAt(options) {
+    const expiresAt = readOption(options.expiresAt);
+    const expiresInDays = readOption(options.expiresInDays);
+    if (expiresAt && expiresInDays) {
+        throw new OxygenError("conflicting_flags", "Pass either --expires-at or --expires-in-days, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (expiresAt) {
+        const date = new Date(expiresAt);
+        if (!Number.isFinite(date.getTime())) {
+            throw new OxygenError("invalid_expires_at", "--expires-at must be a valid ISO 8601 timestamp.", {
+                details: { expires_at: expiresAt },
+                exitCode: 1,
+            });
+        }
+        return date.toISOString();
+    }
+    if (expiresInDays) {
+        const days = readPositiveInt(expiresInDays);
+        if (!days) {
+            throw new OxygenError("invalid_number", "--expires-in-days must be a positive integer.", {
+                details: { value: expiresInDays },
+                exitCode: 1,
+            });
+        }
+        return new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString();
+    }
+    return null;
+}
+export function registerApiKeysFamily(program, handleAsyncAction) {
+    program
+        .command("api-keys")
+        .description("Manage Oxygen CLI API keys for the current organization.")
+        .addCommand(new Command("list")
+        .description("List active CLI API keys for the current user and organization.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("api-keys list", options, () => requestOxygen("/api/cli/api-keys"));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a CLI API key. The token is shown once.")
+        .option("--name <name>", "Key name. Defaults to 'CLI key'.")
+        .option("--expires-at <iso>", "Expiration timestamp as ISO 8601.")
+        .option("--expires-in-days <days>", "Expire the key after this many days.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("api-keys create", options, () => requestOxygen("/api/cli/api-keys", {
+            method: "POST",
+            body: buildApiKeyCreateBody(options),
+        }));
+    }))
+        .addCommand(new Command("revoke")
+        .description("Revoke a CLI API key for the current user and organization.")
+        .argument("<key-id>", "CLI API key id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (keyId, options) => {
+        await handleAsyncAction("api-keys revoke", options, () => requestOxygen(`/api/cli/api-keys/${encodeURIComponent(keyId)}`, {
+            method: "DELETE",
+        }));
+    }));
+}

package/dist/commands/approvals.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerApprovalsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;