@oxygen-agent/cli 1.1014.985 → 1.1014.1087

package/dist/workspace-placement-commands.js

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { readJsonFileValue } from "./command-support.js";
+import { requestOxygen } from "./http-client.js";
+export function registerWorkspacePlacementCommands(root, handle) {
+    root.addCommand(new Command("workspace-test").description("Compare email copy placement in this workspace's connected Google/Microsoft receiving inboxes: Gmail Primary/Promotions and Microsoft Focused/Other. Native sends, 0 additional credits; preview and exact message approval required.")
+        .addCommand(new Command("run").description("Preview a workspace-only copy test. Input JSON: sender_mailbox_ids, receiver_mailbox_ids, variants [{key,subject,body_text,body_html?}]. Approve the same input with returned request_id/plan_hash/rendered_at and max_live_sends. Up to five variants and 50 messages; never buys provider tests or resumes campaigns.")
+        .requiredOption("--input <file>", "JSON test input file.").option("--approved", "Execute the exact reviewed matrix.")
+        .option("--rendered-at <timestamp>", "Rendering timestamp returned by preview; reuse when approving.").option("--tracking-opens", "Preview with open tracking on verified workspace domain.").option("--tracking-clicks", "Preview with click tracking on verified workspace domain.")
+        .option("--request-id <id>", "Request UUID from preview.").option("--plan <hash>", "Exact preview plan hash.").option("--max-live-sends <n>", "Maximum approved diagnostic emails (1–50).")
+        .option("--preview-cursor <id>", "Read the next manifest page using the same input, request ID and rendering time.").option("--preview-limit <n>", "Preview manifest page size (1–20); never use with approval.")
+        .option("--preview-probe-id <id>", "Read exact rendered copy for a preview probe; reuse request ID and rendering time.").option("--preview-part <part>", "body_text or body_html.").option("--preview-offset <n>", "Unicode character offset returned by copy preview.").option("--preview-copy-limit <n>", "Copy page size (1–3000 characters).")
+        .option("--allow-paused-probe", "Explicitly allow diagnostic sends from paused senders, preserving pauses.").option("--json", "Print JSON.")
+        .action(async (options) => handle("deliverability workspace-test run", options, () => {
+        const input = readJsonFileValue(resolve(options.input), "--input");
+        if (!input || typeof input !== "object" || Array.isArray(input))
+            throw new Error("--input must contain a JSON object.");
+        return requestOxygen("/api/cli/deliverability/workspace-tests", { method: "POST", body: { ...input, approved: options.approved === true,
+                ...(options.approved ? { approved: true } : {}), ...(options.requestId ? { request_id: options.requestId } : {}),
+                ...(options.plan ? { plan_hash: options.plan } : {}), ...(options.renderedAt ? { rendered_at: options.renderedAt } : {}), ...(options.trackingOpens ? { tracking_opens: true } : {}), ...(options.trackingClicks ? { tracking_clicks: true } : {}), ...(options.maxLiveSends ? { max_live_sends: Number(options.maxLiveSends) } : {}),
+                ...(options.allowPausedProbe ? { allow_paused_probe: true } : {}),
+                ...(options.previewCursor ? { preview_cursor: options.previewCursor } : {}), ...(options.previewLimit !== undefined ? { preview_limit: Number(options.previewLimit) } : {}),
+                ...(options.previewProbeId ? { preview_probe_id: options.previewProbeId } : {}), ...(options.previewPart ? { preview_part: options.previewPart } : {}), ...(options.previewOffset !== undefined ? { preview_offset: Number(options.previewOffset) } : {}), ...(options.previewCopyLimit !== undefined ? { preview_copy_limit: Number(options.previewCopyLimit) } : {}) } });
+    })))
+        .addCommand(new Command("copy").description("Read a Sequence email step and its copy variants for workspace placement testing. Resolve personalization before preview; no send or charge.").argument("<sequence-id>").option("--step-index <n>", "Zero-based email step index.", "0").option("--json", "Print JSON.")
+        .action(async (id, options) => handle("deliverability workspace-test copy", options, () => requestOxygen(`/api/cli/deliverability/workspace-tests/copy?sequence_id=${encodeURIComponent(id)}&step_index=${encodeURIComponent(options.stepIndex)}`))))
+        .addCommand(new Command("list").description("Read this workspace's recent copy/Primary/Focused placement tests. Saved state only: no send, provider refresh or charge.").option("--cursor <id>", "Next cursor returned by list.").option("--limit <n>", "Tests per page (1–20).").option("--json", "Print JSON.")
+        .action(async (options) => handle("deliverability workspace-test list", options, () => requestOxygen(`/api/cli/deliverability/workspace-tests?${new URLSearchParams({ ...options.cursor ? { cursor: options.cursor } : {}, ...options.limit !== undefined ? { limit: String(options.limit) } : {} })}`))))
+        .addCommand(new Command("get").description("Read one workspace copy test: variant comparison, per-receiver category, partial results and unknowns. No send or provider refresh.").argument("<id>").option("--cursor <id>", "Next receiver-result cursor.").option("--limit <n>", "Receiver results per page (1–20).")
+        .option("--probe <id>", "Read this probe's frozen message copy.").option("--part <part>", "body_text or body_html.").option("--offset <n>", "Returned Unicode character offset.").option("--copy-limit <n>", "Copy page size (1–3000 characters).").option("--json", "Print JSON.")
+        .action(async (id, options) => handle("deliverability workspace-test get", options, () => requestOxygen(`/api/cli/deliverability/workspace-tests/${encodeURIComponent(id)}?${new URLSearchParams({ ...options.cursor ? { cursor: options.cursor } : {}, ...options.limit !== undefined ? { limit: String(options.limit) } : {}, ...options.probe ? { probe_id: options.probe } : {}, ...options.part ? { body_part: options.part } : {}, ...options.offset !== undefined ? { offset: String(options.offset) } : {}, ...options.copyLimit !== undefined ? { copy_limit: String(options.copyLimit) } : {} })}`)))));
+}

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

@@ -40,8 +40,12 @@ export type AgentSessionTeammateRoutine = {
 };
 /** 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;
+/** Staff only: on dev, and in production's staff workspaces (`agentsEnabledIn`; Tim, 2026-10-16). */
 export declare function agentSessionsEnabled(env?: Record<string, string | undefined>): boolean;
+/** Whether this workspace has Ongoing Agent sessions, and so Oxygent routines. */
+export declare function agentSessionsEnabledIn(organizationId: string | null | undefined, env?: Record<string, string | undefined>): boolean;
 export declare function agentSessionsAvailableTo(env: Record<string, string | undefined>, viewer: {
+    organizationId: string | null;
     email: string | null | undefined;
     member: boolean;
     oxygenRole?: string | null | undefined;

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

@@ -1,3 +1,4 @@
+import { agentsEnabled, agentsEnabledIn } from "./agents-enabled.js";
 import { guidedActivationEnabled } from "./guided-activation.js";
 import { validateContract } from "./contracts/schema.js";
 import { GUIDED_ACTIVATION_SCAN_POLICY_CONTRACT } from "./contracts/guided-activation.js";
@@ -10,11 +11,18 @@ export function agentSessionTeammateRoutine(config) {
     const marker = config.teammate_routine;
     return marker && typeof marker.chat_id === "string" ? marker : null;
 }
+/** Staff only: on dev, and in production's staff workspaces (`agentsEnabledIn`; Tim, 2026-10-16). */
 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";
+    return (env.OXYGEN_DEPLOY_ENV === "selfhost-dev" || env.OXYGEN_DEPLOY_ENV === "selfhost-prod")
+        && env.OXYGEN_AGENT_SESSIONS_ENABLED === "staff" && agentsEnabled(env);
+}
+/** Whether this workspace has Ongoing Agent sessions, and so Oxygent routines. */
+export function agentSessionsEnabledIn(organizationId, env = process.env) {
+    return agentSessionsEnabled(env) && agentsEnabledIn(organizationId, env);
 }
 export function agentSessionsAvailableTo(env, viewer) {
-    return agentSessionsEnabled(env) && viewer.member && viewer.oxygenRole !== "client" && (guidedActivationEnabled(env) || isStaffEmail(viewer.email, env));
+    return agentSessionsEnabledIn(viewer.organizationId, env) && viewer.member && viewer.oxygenRole !== "client"
+        && (guidedActivationEnabled(env) || isStaffEmail(viewer.email, env));
 }
 /** Reviewed native adapters. Unknown tools (including generic dispatch and agent management) fail closed. */
 export const AGENT_SESSION_ADAPTERS = {
@@ -124,7 +132,7 @@ export function validateAgentSessionConfig(config, requireResources = true) {
     if (config.guided_activation !== undefined && (!config.teammate_routine
         || !config.guided_activation || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(config.guided_activation.activation_id)
         || !["lead_scan", "morning_briefing"].includes(config.guided_activation.purpose))) {
-        fail("Guided routines require an activation, purpose and private Oxygent chat.");
+        fail("Guided routines require an activation, purpose and bound Oxygent chat.");
     }
     if (config.guided_activation?.purpose === "lead_scan") {
         const policy = config.guided_activation.scan_policy;

package/node_modules/@oxygen/shared/dist/agents-enabled.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where autonomous Agents may run. OXYGEN_AGENTS_ENABLED authorizes Agent run
+ * execution, which carries tool authority and credit spend (feature-gates.ts),
+ * and Oxygents and their routines need it too (ADR 0032).
+ *
+ * - "true" opens every workspace on dev and in tests.
+ * - "staff" opens only the workspaces listed in OXYGEN_AGENTS_WORKSPACE_IDS.
+ * - Production opens only listed workspaces that are also in
+ *   PRODUCTION_AGENT_WORKSPACE_IDS below, whichever value switches it on, so
+ *   Doppler can narrow production but never widen it.
+ * - Shadow never opens, a deployment name nobody knows never opens every
+ *   workspace, and anything else is off, as is an empty list where one is needed.
+ *
+ * Code released before this reads "staff" as off, so the value can be set
+ * ahead of a release without opening anything early.
+ */
+export type AgentsWorkspaceScope = "off" | "all" | ReadonlySet<string>;
+/**
+ * The production workspaces Agents, Oxygents and their routines may run in:
+ * staff workspaces only (Tim, 2026-10-16). Adding a customer's workspace opens
+ * autonomous runs and their spend there, so it needs a founder decision
+ * recorded in OXYGEN_PRODUCT.md and a reviewed change here.
+ */
+export declare const PRODUCTION_AGENT_WORKSPACE_IDS: ReadonlySet<string>;
+export declare function agentsWorkspaceScope(env?: Record<string, string | undefined>): AgentsWorkspaceScope;
+/** Whether Agents run in any workspace here: what a worker loop or family checks before it looks at one. */
+export declare function agentsEnabled(env?: Record<string, string | undefined>): boolean;
+/** Whether Agents run in this workspace. */
+export declare function agentsEnabledIn(organizationId: string | null | undefined, env?: Record<string, string | undefined>): boolean;

package/node_modules/@oxygen/shared/dist/agents-enabled.js

@@ -0,0 +1,51 @@
+import { isProductionData, resolveDeployEnv } from "./deploy-env.js";
+/**
+ * The production workspaces Agents, Oxygents and their routines may run in:
+ * staff workspaces only (Tim, 2026-10-16). Adding a customer's workspace opens
+ * autonomous runs and their spend there, so it needs a founder decision
+ * recorded in OXYGEN_PRODUCT.md and a reviewed change here.
+ */
+export const PRODUCTION_AGENT_WORKSPACE_IDS = new Set([
+    "4257983c-406e-4658-b899-d7ba3cc760a6", // OXYGEN
+    "797d46fe-3e57-4887-98fe-d4793b45dc3a", // Oxygen Demo
+]);
+export function agentsWorkspaceScope(env = process.env) {
+    const flag = env.OXYGEN_AGENTS_ENABLED?.trim().toLowerCase();
+    if (flag !== "true" && flag !== "staff")
+        return "off";
+    const tier = deploymentTier(env);
+    if (tier === "shadow")
+        return "off";
+    if (flag === "true" && tier === "other")
+        return "all";
+    const listed = (env.OXYGEN_AGENTS_WORKSPACE_IDS ?? "")
+        .split(",")
+        .map((id) => id.trim().toLowerCase())
+        .filter((id) => id.length > 0 && (tier !== "prod" || PRODUCTION_AGENT_WORKSPACE_IDS.has(id)));
+    return listed.length > 0 ? new Set(listed) : "off";
+}
+/** Whether Agents run in any workspace here: what a worker loop or family checks before it looks at one. */
+export function agentsEnabled(env = process.env) {
+    return agentsWorkspaceScope(env) !== "off";
+}
+/** Whether Agents run in this workspace. */
+export function agentsEnabledIn(organizationId, env = process.env) {
+    const scope = agentsWorkspaceScope(env);
+    if (scope === "off")
+        return false;
+    if (scope === "all")
+        return true;
+    return typeof organizationId === "string" && scope.has(organizationId.trim().toLowerCase());
+}
+function deploymentTier(env) {
+    try {
+        const { tier } = resolveDeployEnv(env);
+        if (tier === "prod" || tier === "shadow")
+            return tier;
+        // Managed dev telemetry can still carry production data via NODE_ENV.
+        return isProductionData(env) ? "prod" : "other";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -423,7 +423,7 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         primitive: "agents",
         owns: "Adaptive governed worker definitions, versions, authorization, context, triggers, threads, checkpoints, inference, and first-class runs.",
         notFor: "A known deterministic graph that belongs in Workflows or an opaque uploaded runtime.",
-        execution: "Publish and run a governed Agent with explicit tool authority and bounded spend. Staff on dev can create ongoing sessions: draft, exact resource scope, per-run and rolling 24-hour caps, preview/activate, continuing conversation and bounded self-scheduling. Inspect agent session templates; pause/resume preserves history. Staff on dev also talk to Oxygents (AI teammates): the workspace's first one (New Bot until named) and any others added, one ongoing private chat each. A new one is its owner's until shared with everyone in the workspace or named people, as collaborators (a chat of their own) or managers (also its profile and who has access). Group chats hold up to six Oxygents and, if you like, teammates: their admins change who is in them, and each message goes to the Oxygents it @mentions or is for.",
+        execution: "Publish and run a governed Agent with explicit tool authority and bounded spend. Where admitted, staff can create ongoing sessions: draft, exact resource scope, per-run and rolling 24-hour caps, preview/activate, continuing conversation and bounded self-scheduling. Inspect agent session templates; pause/resume preserves history. Where admitted, Oxygents (AI teammates) default to Workspace: one ongoing chat shared by everyone with access. Choose visibility personal when creating one for creator-only access; an API key acts as its issuing person. Home stays Workspace. Owners change visibility with confirm_visibility: publishing shares all existing history; Personal keeps history but removes others' future access and cannot retract what they saw. Collaborators use the shared chat; managers also change its profile and access. everyone off restricts Workspace access to its owner and named people, with workspace administrators retaining management access; it does not make it Personal. Group chats hold up to six Oxygents and optional teammates; messages go to the Oxygents mentioned or addressed.",
         posture: "mixed",
         gatewayTools: ["oxygen_agent_list", "oxygen_agent_create", "oxygen_agent_run"],
         gatewayCommands: ["agent list", "agent create", "agent run"],
@@ -1545,6 +1545,26 @@ function sentLinkedInInvitationReadRecommendation(query) {
         execution: "Read one live, free pending-sent invitation page with oxygen_linkedin_invites_sent via oxygen_capabilities_read; CLI twin: oxygen linkedin invitations list --account <ref> --limit <n> --cursor <token> --json. Resolve the sender with oxygen_senders_list. Resume invitations.cursor unchanged with the same account; a full v2 page can need one empty final page. No provider writes or credits. Recurring received/sent capture is linkedin invitations setup; withdrawal is a separate external action.",
     };
 }
+/** Workspace chat assistants are Oxygents; external app workspace selection stays separate. */
+function isOxygentChatIntent(query) {
+    if (isWorkspacePagesIntent(query) || isSecondPartyDecisionIntent(query))
+        return false;
+    if (/\boxygents?\b/.test(query))
+        return true;
+    if (/\b(chatgpt|claude|codex|oauth|mcp|connectors?|connected apps?)\b/.test(query))
+        return false;
+    const chatPrivacy = /\b(chats?|conversations?|histor(?:y|ies)|visibility|shared|private|personal)\b/.test(query);
+    if (/\bai (?:assistants?|teammates?)\b/.test(query))
+        return chatPrivacy;
+    // Human membership asks must not re-enter Oxygent mutations through the
+    // generic fallback after the user-facing routine router excludes them.
+    // Explicit Oxygent/AI teammate access above keeps its native owner.
+    if (/\b(?:invite|members?|membership|permissions?|roles?|human|colleague|coworker)\b/.test(query))
+        return false;
+    return /\b(?:assistants?|teammates?)\b/.test(query)
+        && /\b(chats?|conversations?|histor(?:y|ies)|visibility)\b/.test(query)
+        && /\b(shared|private|personal|workspace|team|visibility)\b/.test(query);
+}
 /**
  * The apps a person connected with OAuth and where each one works: "make
  * ChatGPT always use workspace X", "default workspace for my Claude
@@ -2050,6 +2070,8 @@ function explicitCapabilityIntent(query) {
     const readOnly = readInspectionRecommendation(query);
     if (readOnly)
         return ROUTE_BY_ID.get(readOnly.capabilityId) ?? null;
+    if (isOxygentChatIntent(query))
+        return ROUTE_BY_ID.get("agents") ?? null;
     // Importing an AI answer is GEO evidence, rather than a Table file import.
     if (/\b(?:geo|aeo|ai (?:(?:search|answer) )?visibility|consumer ai answers?|answer engine optimization|generative engine optimization)\b/.test(query))
         return ROUTE_BY_ID.get("geo") ?? null;
@@ -2395,6 +2417,13 @@ function isPublishingPostIntent(query) {
         && !(/\b(find|search|scrape|research)\b/.test(query) && /\b(about|mention|containing)\b/.test(query));
 }
 function recommendationsFor(card, query) {
+    if (card.id === "agents" && isOxygentChatIntent(query)) {
+        const continuing = /\b(continue|resume|talk)\b|\b(?:read|send|post)\b.*\b(?:chat|conversation|message)s?\b/.test(query);
+        return {
+            tools: ["oxygen_oxygents_create", "oxygen_oxygents_update", "oxygen_oxygents_access", ...(continuing ? ["oxygen_oxygents_get", "oxygen_oxygents_message"] : [])],
+            commands: ["oxygents create", "oxygents update", "oxygents access", ...(continuing ? ["oxygents get", "oxygents message"] : [])],
+        };
+    }
     if (card.id === "billing-and-budgets" && isPartnerBonusReadIntent(query)) {
         return { tools: ["oxygen_billing_summary"], commands: ["billing summary"] };
     }
@@ -3291,11 +3320,19 @@ function isConnectionPriceIntent(query) {
  * it. Sending, network, profile and post asks keep their own owners.
  */
 function isLinkedInAccountConnectIntent(query) {
+    // Exact native command discovery has no LinkedIn noun to score.
+    if (/^(?:oxygen )?senders connect$/.test(query))
+        return true;
     if (!/\b(linkedin|unipile)\b/.test(query))
         return false;
     if (/^(linkedin|unipile)( accounts?)?$/.test(query))
         return true;
-    if (/\b(send|sending|enroll|sequence|campaign|cadence|messages?|dms?|invites?|invitations?|posts?|profiles?|network|connections|followers|viewers|limits|hours|ads?|scrape|research|company|companies|url|pac(?:e|ing)|spacing|spaced|spread|apart|throttl\w*)\b/.test(query))
+    const authenticationUrl = /\b(?:authentication|authorization|oauth|auth)\b/.test(query)
+        && /\b(?:url|link)\b/.test(query)
+        && /\b(?:connect|reconnect|account|sender)\b/.test(query);
+    if (/\burl\b/.test(query) && !authenticationUrl)
+        return false;
+    if (/\b(send|sending|enroll|sequence|campaign|cadence|messages?|dms?|invites?|invitations?|posts?|profiles?|network|connections|followers|viewers|limits|hours|ads?|scrape|research|company|companies|pac(?:e|ing)|spacing|spaced|spread|apart|throttl\w*)\b/.test(query))
         return false;
     return /\b(connect|reconnect|link|add|accounts?|senders?|seats?|free|plan)\b/.test(query);
 }

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

@@ -23,7 +23,7 @@ function agentSessionOperation(id, verb, method, suffix, summary, fields = {}, r
     };
 }
 export const AGENT_SESSION_OPERATIONS = [
-    agentSessionOperation("agent.sessions.templates", "templates", "GET", "/templates", "Discover eight ongoing Agent job templates, reviewed actions, required resources, the full config schema and a draft example. Staff on dev only; legacy Agents remain available."),
+    agentSessionOperation("agent.sessions.templates", "templates", "GET", "/templates", "Discover eight ongoing Agent job templates, reviewed actions, required resources, the full config schema and a draft example. Dev only; requires a current non-client workspace member and enabled sessions. Legacy Agents remain available."),
     agentSessionOperation("agent.sessions.list", "list", "GET", "", "List independent ongoing sessions under an Agent, including status, next check and spend."),
     agentSessionOperation("agent.sessions.create", "create", "POST", "", "Create a draft ongoing session. Explicit caps are required; review and activate separately.", { config: AGENT_SESSION_CONFIG_CONTRACT }, ["config"]),
     agentSessionOperation("agent.sessions.get", "get", "GET", "/{session}", "Read this session's configuration revision, conversation, memory, next check, approvals and budget reservations."),

package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js

@@ -91,7 +91,7 @@ export const CUSTOMER_OPERATIONS = [
     operation("tables.import.csv", "/api/cli/tables/import-csv", "POST", "tables import-csv", "oxygen_tables_import_csv", "tables", "Import inline CSV into a hosted Table through its durable ingestion run. Use staged upload for large files.", { csv_text: text(), csv_base64: text(), table: text(), table_name: text(), project: text(), filename: text(), upsert_key: text(), skip_blank_cells: skipBlankCells(), batch_size: int({ minimum: 1, maximum: 5000 }) }, [], cliOnly),
     operation("tables.import.prepare", "/api/cli/tables/import-url", "POST", "tables import-upload", "oxygen_tables_import_upload", "tables", "Prepare a scoped storage upload for a hosted Table import; uploads and imports are separate, inspectable steps.", { file_name: text(), content_type: text(), byte_length: int({ minimum: 1 }), trace_id: text(), format: enumOf(["csv", "json", "xlsx"]) }, ["file_name", "byte_length"]),
     operation("tables.import.preview", "/api/cli/tables/import-preview", "POST", "tables import-preview", "oxygen_tables_import_preview", "tables", "Preview a staged file's headers, rows and existing-table mapping; writes no imported rows.", { storage_key: text(), file_name: text(), format: enumOf(["csv", "json", "xlsx"]), byte_length: int({ minimum: 1 }), table: text(), upsert_key: text() }, ["storage_key", "byte_length"], { mutates: false }),
-    operation("tables.import.staged", "/api/cli/tables/import-staged", "POST", "tables import-staged", "oxygen_tables_import_staged", "tables", "Start a durable hosted import from this workspace's staged file; choose an existing table or create_name.", { table: text(), create_name: text(), project: text(), storage_key: text(), storage_bucket: text(), storage_provider: enumOf(["s3"]), file_name: text(), format: enumOf(["csv", "json", "xlsx"]), sha256: text(), upsert_key: text(), skip_blank_cells: skipBlankCells(), source_key_map: json, byte_length: int({ minimum: 1 }), row_count: int({ minimum: 1 }), max_concurrency: int({ minimum: 1, maximum: 1000 }), source: enumOf(["cli", "mcp", "web"]), batch_size: int({ minimum: 1, maximum: 5000 }) }, ["storage_key", "byte_length"]),
+    operation("tables.import.staged", "/api/cli/tables/import-staged", "POST", "tables import-staged", "oxygen_tables_import_staged", "tables", "Import a staged file into a table or a new create_name table.", { table: text(), create_name: text(), project: text(), storage_key: text(), storage_bucket: text(), storage_provider: enumOf(["s3"]), file_name: text(), format: enumOf(["csv", "json", "xlsx"]), sha256: text(), upsert_key: text(), skip_blank_cells: skipBlankCells(), source_key_map: json, ignore_source_keys: list(), byte_length: int({ minimum: 1 }), row_count: int({ minimum: 1 }), max_concurrency: int({ minimum: 1, maximum: 1000 }), source: enumOf(["cli", "mcp", "web"]), batch_size: int({ minimum: 1, maximum: 5000 }) }, ["storage_key", "byte_length"]),
     operation("tables.import.file", "/api/cli/tables/import-file", "POST", "tables import-file", "oxygen_tables_import_file", "tables", "Import small base64 file bytes through the shared multipart import API; use staged upload for large files.", { content_base64: text(), file_name: text(), content_type: text(), table: text(), table_name: text(), project: text(), format: enumOf(["csv", "json", "xlsx"]), sheet: text(), upsert_key: text(), source_key_map: json, source_hash: text(), batch_size: int({ minimum: 1, maximum: 5000 }), max_concurrency: int({ minimum: 1 }) }, ["content_base64", "file_name"], { multipart: { contentField: "content_base64", nameField: "file_name", typeField: "content_type", fileField: "file" } }),
     operation("tables.link.suggest", "/api/cli/tables/link/suggest", "POST", "tables link-suggest", "oxygen_tables_link_suggest", "tables", "Plan column links and matching row counts between Tables; creates no relation. Apply with tables link --to (MCP oxygen_tables_link_bulk).", TABLE_LINK_SUGGEST_CONTRACT.properties, ["table", "to"], { mutates: false }),
     operation("tables.recover_pending", "/api/cli/tables/recover-pending", "POST", "tables recover-pending", "oxygen_tables_recover_pending", "tables", "Recover BetterContact email/phone requests and read verification blockers; no new orders or imports.", TABLE_RECOVER_PENDING_CONTRACT.properties, ["table"], { ...mcpOnly, annotations: { openWorldHint: true } }),

package/node_modules/@oxygen/shared/dist/contracts/guided-activation.js

@@ -39,8 +39,8 @@ export const GUIDED_ACTIVATION_OPERATIONS = [
         cli: { path: ["onboarding", "activation", "status"], summary: "Resume your guided onboarding and native resource links. Enabled genuine dev only; current non-client workspace members." },
         mcp: { name: "oxygen_onboarding_activation_status", title: "Oxygen: Onboarding status", description: "Read your resumable guided onboarding and native links. Enabled genuine dev only; current non-client workspace members.", pack: "agents" }, mutates: false, spends: false },
     { id: "onboarding.activation.start", route: "/api/cli/onboarding/activation", method: "POST", contract: GUIDED_ACTIVATION_START_CONTRACT,
-        cli: { path: ["onboarding", "activation", "start"], summary: "Prepare your activation and private Oxygent chat. Free; no message send or outreach." },
-        mcp: { name: "oxygen_onboarding_activation_start", title: "Oxygen: Start onboarding record", description: "Prepare your activation with operating_path own_agent or oxygent. The oxygent path binds its native workspace Agent and creator-private chat. Free; no turn, inference, provider or outreach dispatch. Enabled genuine dev only; current non-client workspace members.", pack: "agents" }, mutates: true, spends: false },
+        cli: { path: ["onboarding", "activation", "start"], summary: "Prepare your creator-only activation and Oxygent chat: Workspace shared, Personal creator-only. Free; no send or outreach." },
+        mcp: { name: "oxygen_onboarding_activation_start", title: "Oxygen: Start onboarding record", description: "Prepare your creator-only activation with operating_path own_agent or oxygent. Oxygent binds its native Agent/chat: Workspace shared, Personal creator-only. Free; no turn, inference, provider or outreach dispatch. Enabled genuine dev only; current non-client workspace members.", pack: "agents" }, mutates: true, spends: false },
     { id: "onboarding.activation.get", route: "/api/cli/onboarding/activation/{activationId}", method: "GET", parameters: ["activationId"], contract: obj({}),
         cli: { path: ["onboarding", "activation", "get"], summary: "Read your activation by ID and its native resource links." },
         mcp: { name: "oxygen_onboarding_activation_get", title: "Oxygen: Read onboarding record", description: "Read your activation by activationId. Only its creator can read it. Enabled genuine dev only; current non-client workspace members.", pack: "agents" }, mutates: false, spends: false },
@@ -51,9 +51,9 @@ export const GUIDED_ACTIVATION_OPERATIONS = [
         cli: { path: ["onboarding", "activation", "first-leads"], summary: "Create or resume the activation-owned First leads Table. Free; no discovery, enrichment or outreach." },
         mcp: { name: "oxygen_onboarding_activation_first_leads", title: "Oxygen: First leads Table", description: "Create or resume one native First leads Table for your activationId. Free; no discovery, enrichment, enrollment or outreach. Use native search/ingestion separately.", pack: "agents" }, mutates: true, spends: false },
     { id: "onboarding.activation.routines_preview", route: "/api/cli/onboarding/activation/{activationId}/routines/preview", method: "POST", parameters: ["activationId"], contract: GUIDED_ACTIVATION_ROUTINES_PREVIEW_CONTRACT,
-        cli: { path: ["onboarding", "activation", "routines-preview"], summary: "Review two explicitly configured draft routines, exact native source scope and caps. Arms no schedule." },
-        mcp: { name: "oxygen_onboarding_activation_routines_preview", title: "Oxygen: Review daily routines", description: "Build native scan/briefing drafts and exact previews for activationId. Requires confirmed IANA timezone, both local times, source_ids and caps. Native Table sources quote zero; original ingestion sources need a current quote. Arms no schedule.", pack: "agents" }, mutates: true, spends: false },
+        cli: { path: ["onboarding", "activation", "routines-preview"], summary: "Save two routine draft configurations; review exact native source scope and caps. Arms no schedule." },
+        mcp: { name: "oxygen_onboarding_activation_routines_preview", title: "Oxygen: Review daily routines", description: "Save scan/briefing draft configuration and exact previews for activationId. Requires confirmed IANA timezone, both local times, source_ids and caps. Native Table sources quote zero; original ingestion sources need a current quote. Arms no schedule.", pack: "agents" }, mutates: true, spends: false },
     { id: "onboarding.activation.routine_activate", route: "/api/cli/onboarding/activation/{activationId}/routines/activate", method: "POST", parameters: ["activationId"], contract: GUIDED_ACTIVATION_ROUTINE_ACTIVATE_CONTRACT,
         cli: { path: ["onboarding", "activation", "routine-activate"], summary: "Activate one exact routine preview at its native revision. Requires approval or valid current creator-chat auto-approve authority." },
-        mcp: { name: "oxygen_onboarding_activation_routine_activate", title: "Oxygen: Activate daily routine", description: "Activate one lead_scan or morning_briefing at exact native revision and preview_token. Requires approved=true or current auto-approve authority in the creator's bound private chat. Schedules are independent and remain capped; no automatic enrollment.", pack: "agents" }, mutates: true, spends: true },
+        mcp: { name: "oxygen_onboarding_activation_routine_activate", title: "Oxygen: Activate daily routine", description: "Activate lead_scan or morning_briefing at exact revision/preview_token. Requires approved=true or current creator auto-approve authority in the bound chat. Workspace shared; Personal creator-only. Separate capped schedules; no automatic enrollment.", pack: "agents" }, mutates: true, spends: true },
 ];

package/node_modules/@oxygen/shared/dist/contracts/guided-company-files.d.ts

@@ -0,0 +1,30 @@
+import { type ContractIssue } from "./schema.js";
+import type { OperationSpec } from "./operations.js";
+export declare const GUIDED_COMPANY_FILE_UPLOAD_CONTRACT: import("./schema.js").ContractObject<{
+    readonly revision: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly upload_id: import("./schema.js").StringProperty;
+    readonly sha256: import("./schema.js").StringProperty;
+    readonly size_bytes: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly file_name: import("./schema.js").StringProperty;
+    readonly content_type: {
+        type: "string";
+        enum: readonly ("application/pdf" | "text/markdown" | "text/plain")[];
+        description?: string;
+    };
+    readonly content_base64: import("./schema.js").StringProperty;
+}, "content_base64" | "content_type" | "file_name" | "revision" | "sha256" | "size_bytes" | "upload_id">;
+/** Raw wire values are never trimmed or renamed; the native owner verifies original SHA/bytes. */
+export declare function guidedCompanyFileUploadInputIssues(args: Readonly<Record<string, unknown>>): readonly ContractIssue[];
+export declare const GUIDED_COMPANY_FILE_UPLOAD_OPERATION: OperationSpec;

package/node_modules/@oxygen/shared/dist/contracts/guided-company-files.js

@@ -0,0 +1,53 @@
+import { GUIDED_COMPANY_FILE_CONTENT_TYPES, GUIDED_COMPANY_FILE_LIMITS, guidedCompanyFileByteLimit } from "../guided-company-files.js";
+import { enumOf, int, obj, str } from "./schema.js";
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+export const GUIDED_COMPANY_FILE_UPLOAD_CONTRACT = obj({
+    revision: int({ minimum: 1 }), upload_id: str({ pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }),
+    sha256: str({ pattern: "^[0-9a-f]{64}$" }), size_bytes: int({ minimum: 1, maximum: GUIDED_COMPANY_FILE_LIMITS.pdfBytes }),
+    file_name: str({ minLength: 1, maxLength: GUIDED_COMPANY_FILE_LIMITS.nameBytes }),
+    content_type: enumOf(GUIDED_COMPANY_FILE_CONTENT_TYPES),
+    content_base64: str({ minLength: 4, maxLength: 4 * Math.ceil(GUIDED_COMPANY_FILE_LIMITS.pdfBytes / 3) }),
+}, { required: ["revision", "upload_id", "sha256", "size_bytes", "file_name", "content_type", "content_base64"] });
+/** Raw wire values are never trimmed or renamed; the native owner verifies original SHA/bytes. */
+export function guidedCompanyFileUploadInputIssues(args) {
+    const issues = [];
+    const issue = (path, message) => issues.push({ path, message });
+    for (const key of ["activationId", "upload_id"])
+        if (typeof args[key] !== "string" || !uuid.test(args[key]))
+            issue(key, "Use a native UUID.");
+    const name = args.file_name;
+    if (typeof name !== "string" || !name.trim() || /[\\/\u0000-\u001f\u007f]/u.test(name) || new TextEncoder().encode(name).length > GUIDED_COMPANY_FILE_LIMITS.nameBytes)
+        issue("file_name", "Use a filename without paths or controls, at most 255 UTF-8 bytes.");
+    const type = args.content_type;
+    if (!GUIDED_COMPANY_FILE_CONTENT_TYPES.includes(type))
+        issue("content_type", "Use UTF-8 text, Markdown or PDF.");
+    else if (typeof args.size_bytes !== "number" || args.size_bytes > guidedCompanyFileByteLimit(type))
+        issue("size_bytes", "Use at most 1500000 text bytes or 5242880 PDF bytes.");
+    const encoded = args.content_base64;
+    if (typeof encoded !== "string" || !encoded || encoded.length % 4 !== 0 || /[^A-Za-z0-9+/=]/u.test(encoded) || !/^[^=]*={0,2}$/u.test(encoded))
+        issue("content_base64", "Use canonical non-empty base64 file bytes.");
+    else {
+        try {
+            const decoded = atob(encoded);
+            if (btoa(decoded) !== encoded)
+                issue("content_base64", "Use canonical base64 without altered padding bits.");
+            if (decoded.length !== args.size_bytes)
+                issue("size_bytes", "size_bytes must equal the original decoded byte length.");
+        }
+        catch {
+            issue("content_base64", "Use valid base64 file bytes.");
+        }
+    }
+    return issues;
+}
+export const GUIDED_COMPANY_FILE_UPLOAD_OPERATION = {
+    id: "onboarding.company_files.upload", route: "/api/cli/onboarding/activation/{activationId}/company-files", method: "POST",
+    parameters: ["activationId"], contract: GUIDED_COMPANY_FILE_UPLOAD_CONTRACT, inputCheck: guidedCompanyFileUploadInputIssues,
+    multipart: { contentField: "content_base64", nameField: "file_name", typeField: "content_type", fileField: "file",
+        fileMetadata: { sha256Field: "sha256", sizeBytesField: "size_bytes" } },
+    cli: { path: ["onboarding", "company-files", "upload"], summary: "Upload an optional company source file for your private DEV onboarding activation." },
+    mcp: { name: "oxygen_onboarding_company_files_upload", title: "Oxygen: Upload onboarding company file", pack: "agents",
+        description: "Current creator and revision only, genuine enabled DEV: upload UTF-8 text/Markdown up to 1500000 bytes or PDF up to 5242880 bytes. Supply original filename, MIME, size and SHA-256 plus stable upload_id UUID; exact retries reuse the native file. PDF retains original bytes with text unavailable. No account connection, parser, model or message send.",
+        annotations: { destructiveHint: false, openWorldHint: true, idempotentHint: true } },
+    mutates: true, spends: false,
+};

package/node_modules/@oxygen/shared/dist/contracts/guided-first-sourcing.d.ts

@@ -0,0 +1,120 @@
+import { type ContractIssue } from "./schema.js";
+import type { OperationSpec } from "./operations.js";
+/** Matches the actual native people-search and page safety ceilings. */
+export declare const GUIDED_FIRST_SOURCING_LIMITS: {
+    readonly targetCount: 50000;
+    readonly maxPages: 1000;
+};
+export declare const GUIDED_FIRST_SOURCING_BOUNDS_CONTRACT: import("./schema.js").ContractObject<{
+    readonly targetCount: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly maxPages: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly maxCredits: {
+        readonly type: "number";
+        readonly description?: string;
+        readonly minimum?: number;
+        readonly maximum?: number;
+        readonly "x-clamp"?: true;
+        readonly exclusiveMinimum: 0;
+    };
+}, "maxCredits" | "maxPages" | "targetCount">;
+export declare const GUIDED_FIRST_SOURCING_PREVIEW_CONTRACT: import("./schema.js").ContractObject<{
+    revision: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    bounds: import("./schema.js").ContractObject<{
+        readonly targetCount: {
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        };
+        readonly maxPages: {
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        };
+        readonly maxCredits: {
+            readonly type: "number";
+            readonly description?: string;
+            readonly minimum?: number;
+            readonly maximum?: number;
+            readonly "x-clamp"?: true;
+            readonly exclusiveMinimum: 0;
+        };
+    }, "maxCredits" | "maxPages" | "targetCount">;
+}, "bounds" | "revision">;
+export declare const GUIDED_FIRST_SOURCING_RUN_CONTRACT: import("./schema.js").ContractObject<{
+    readonly revision: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly bounds: import("./schema.js").ContractObject<{
+        readonly targetCount: {
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        };
+        readonly maxPages: {
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        };
+        readonly maxCredits: {
+            readonly type: "number";
+            readonly description?: string;
+            readonly minimum?: number;
+            readonly maximum?: number;
+            readonly "x-clamp"?: true;
+            readonly exclusiveMinimum: 0;
+        };
+    }, "maxCredits" | "maxPages" | "targetCount">;
+    readonly previewId: import("./schema.js").StringProperty;
+    readonly previewDigest: import("./schema.js").StringProperty;
+    readonly approved: import("./schema.js").BooleanProperty;
+}, "approved" | "bounds" | "previewDigest" | "previewId" | "revision">;
+export declare const GUIDED_FIRST_SOURCING_GET_CONTRACT: import("./schema.js").ContractObject<{
+    readonly revision: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly generation: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly timezoneHint: import("./schema.js").StringProperty;
+}, never>;
+export declare function guidedFirstSourcingGetInputIssues(args: Readonly<Record<string, unknown>>): readonly ContractIssue[];
+export type GuidedFirstSourcingAction = "get" | "preview" | "run";
+export declare const GUIDED_FIRST_SOURCING_OPERATIONS: readonly OperationSpec[];

package/node_modules/@oxygen/shared/dist/contracts/guided-first-sourcing.js

@@ -0,0 +1,48 @@
+import { bool, int, num, obj, str } from "./schema.js";
+import { isValidTimeZone } from "../zoned-time.js";
+/** Matches the actual native people-search and page safety ceilings. */
+export const GUIDED_FIRST_SOURCING_LIMITS = { targetCount: 50000, maxPages: 1000 };
+export const GUIDED_FIRST_SOURCING_BOUNDS_CONTRACT = obj({
+    targetCount: int({ minimum: 1, maximum: GUIDED_FIRST_SOURCING_LIMITS.targetCount }),
+    maxPages: int({ minimum: 1, maximum: GUIDED_FIRST_SOURCING_LIMITS.maxPages }),
+    maxCredits: { ...num(), exclusiveMinimum: 0 },
+}, { required: ["targetCount", "maxPages", "maxCredits"] });
+const request = { revision: int({ minimum: 1 }), bounds: GUIDED_FIRST_SOURCING_BOUNDS_CONTRACT };
+export const GUIDED_FIRST_SOURCING_PREVIEW_CONTRACT = obj(request, { required: ["revision", "bounds"] });
+export const GUIDED_FIRST_SOURCING_RUN_CONTRACT = obj({ ...request,
+    previewId: str({ minLength: 36, maxLength: 36, pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }),
+    previewDigest: str({ minLength: 64, maxLength: 64, pattern: "^[a-f0-9]{64}$" }), approved: bool(),
+}, { required: ["revision", "bounds", "previewId", "previewDigest", "approved"] });
+export const GUIDED_FIRST_SOURCING_GET_CONTRACT = obj({
+    revision: int({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+    generation: int({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+    timezoneHint: str({ minLength: 1, maxLength: 80, description: "Provisional saved/browser IANA hint for current nightly defaults; never confirms a schedule." }),
+});
+export function guidedFirstSourcingGetInputIssues(args) {
+    const fields = ["revision", "generation", "timezoneHint"];
+    if (!fields.some(field => args[field] !== undefined))
+        return [];
+    const issues = fields.filter(field => args[field] === undefined).map(path => ({ path,
+        message: "Supply revision, generation and timezoneHint together to read current routine defaults." }));
+    if (typeof args.timezoneHint !== "string" || args.timezoneHint !== args.timezoneHint.trim() || !isValidTimeZone(args.timezoneHint)) {
+        issues.push({ path: "timezoneHint", message: "Use a valid customer/browser IANA timezone suggestion; no schedule is confirmed." });
+    }
+    return issues;
+}
+const base = "/api/cli/onboarding/activation/{activationId}/first-sourcing";
+export const GUIDED_FIRST_SOURCING_OPERATIONS = [
+    { id: "onboarding.first_sourcing.get", route: base, method: "GET", contract: GUIDED_FIRST_SOURCING_GET_CONTRACT, inputCheck: guidedFirstSourcingGetInputIssues, parameters: ["activationId"],
+        cli: { path: ["onboarding", "first-sourcing", "get"], summary: "Read first sourcing; optionally quote current nightly defaults with revision, generation and timezoneHint." },
+        mcp: { name: "oxygen_onboarding_first_sourcing_get", title: "Oxygen: Read first sourcing", pack: "agents",
+            description: "Read the current creator-private DEV source, native ingestion receipt and actual settled continuation. No sourcing provider call or new sourcing; historical approval cannot authorize another pull. Verifies native billing and may reconcile an earned grant. Optional revision, generation and provisional IANA timezoneHint together return current native nightly defaults after the source transaction; no draft, schedule confirmation or approval.", annotations: { openWorldHint: true } }, mutates: true, spends: false },
+    { id: "onboarding.first_sourcing.preview", route: `${base}/preview`, method: "POST", parameters: ["activationId"], contract: GUIDED_FIRST_SOURCING_PREVIEW_CONTRACT,
+        cli: { path: ["onboarding", "first-sourcing", "preview"], summary: "Review a bounded native first pull into First leads; no provider search." },
+        mcp: { name: "oxygen_onboarding_first_sourcing_preview", title: "Oxygen: Preview first sourcing", pack: "agents",
+            description: "Current creator and revision, confirmed company, saved audience and eligible trial/paid billing required. Bounds contain targetCount, maxPages and maxCredits. Creates/reuses the native First leads Table and persists a managed source quote. Returns previewId/digest; no provider search, model or outreach.",
+            annotations: { openWorldHint: true, destructiveHint: false } }, mutates: true, spends: false },
+    { id: "onboarding.first_sourcing.run", route: `${base}/run`, method: "POST", parameters: ["activationId"], contract: GUIDED_FIRST_SOURCING_RUN_CONTRACT,
+        cli: { path: ["onboarding", "first-sourcing", "run"], summary: "Approve the exact stored preview and caps; enqueue or recover the same native first-source run." },
+        mcp: { name: "oxygen_onboarding_first_sourcing_run", title: "Oxygen: Run first sourcing", pack: "agents",
+            description: "approved=true plus stored previewId/previewDigest, current revision and identical bounds authorize the reviewed managed people source into the activation's First leads Table. Current native admission, billing, quote and worker fences apply. Retry/Back/Restart with the same actual source recovers its native run. No model, enrollment or outreach.",
+            annotations: { openWorldHint: true, destructiveHint: false, idempotentHint: true } }, mutates: true, spends: true },
+];