@oxygen-agent/cli 1.275.1 → 1.284.3

package/dist/knowledge-mirror.d.ts

@@ -92,6 +92,28 @@ export declare function acquireMirrorLock(dir: string, options?: {
 export declare function releaseMirrorLock(dir: string): void;
 export declare function writeGeneratedIndexFile(dir: string, index: MirrorIndexSnapshot): void;
 export declare function writeGeneratedLogFile(dir: string, entries: MirrorLogEntry[]): void;
+export type MirrorPushCandidate = {
+    slug: string;
+    /** dirty = tracked page whose local bytes drifted; new = untracked local file. */
+    kind: "dirty" | "new";
+    path: string;
+    /** Manifest record for dirty pages — its revision is the optimistic-concurrency base. */
+    record?: MirrorPageRecord;
+};
+export type MirrorPushPlan = {
+    candidates: MirrorPushCandidate[];
+    skipped: Array<{
+        file: string;
+        reason: "invalid_slug" | "reserved_slug" | "generated_file";
+    }>;
+};
+/**
+ * Scan the mirror for pushable local state: tracked pages whose bytes drifted
+ * from the manifest sha (edited locally) and untracked `.md` files (created
+ * locally). Generated index/log summaries and reserved slugs are skipped.
+ * Read-only — the push command decides what to do with the plan.
+ */
+export declare function planMirrorPush(dir: string, state: MirrorState | null): MirrorPushPlan;
 /** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
 export declare function purgeMirror(dir: string): void;
 /**

package/dist/knowledge-mirror.js

@@ -327,6 +327,62 @@ function writeGeneratedFile(dir, name, lines) {
 function oneLine(value) {
     return value.replace(/\s+/g, " ").trim();
 }
+// Slugs the server write path refuses (RESERVED_KNOWLEDGE_SLUGS) — an untracked
+// local file under one of these names can never push. A TRACKED page under one
+// (legacy rows may predate the reservation) still pushes by id.
+const PUSH_RESERVED_SLUGS = new Set(["index", "log", "schema", "company-profile", "readme"]);
+/**
+ * Scan the mirror for pushable local state: tracked pages whose bytes drifted
+ * from the manifest sha (edited locally) and untracked `.md` files (created
+ * locally). Generated index/log summaries and reserved slugs are skipped.
+ * Read-only — the push command decides what to do with the plan.
+ */
+export function planMirrorPush(dir, state) {
+    const plan = { candidates: [], skipped: [] };
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return plan; // no mirror directory — nothing to push
+    }
+    for (const entry of entries.sort((a, b) => a.localeCompare(b))) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const slug = entry.slice(0, -3);
+        const path = join(dir, entry);
+        const record = state?.pages[slug];
+        if (record) {
+            if (isFileDirty(dir, slug, record.content_sha256)) {
+                plan.candidates.push({ slug, kind: "dirty", path, record });
+            }
+            continue;
+        }
+        if (slug.length > MIRROR_SLUG_MAX_LENGTH || !MIRROR_SLUG_PATTERN.test(slug)) {
+            plan.skipped.push({ file: entry, reason: "invalid_slug" });
+            continue;
+        }
+        // Untracked generated summaries (index.md / log.md before their slugs are
+        // ever page-backed) carry the marker header — never push those.
+        let head = "";
+        try {
+            head = readFileSync(path, "utf8").slice(0, GENERATED_MIRROR_FILE_HEADER.length);
+        }
+        catch {
+            continue;
+        }
+        if (head === GENERATED_MIRROR_FILE_HEADER) {
+            plan.skipped.push({ file: entry, reason: "generated_file" });
+            continue;
+        }
+        if (PUSH_RESERVED_SLUGS.has(slug)) {
+            plan.skipped.push({ file: entry, reason: "reserved_slug" });
+            continue;
+        }
+        plan.candidates.push({ slug, kind: "new", path });
+    }
+    return plan;
+}
 // ── Purge ───────────────────────────────────────────────────────────────────────
 /** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
 export function purgeMirror(dir) {

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

@@ -26,6 +26,8 @@ export type PricingPlanDefinition = {
 };
 export type PricingPlanMetadata = Record<string, unknown> | null | undefined;
 export declare const CONTACT_SALES_URL = "https://cal.com/tim-scheuer-mxbib9/45";
+export declare const TRIAL_PERIOD_DAYS = 7;
+export declare const TRIAL_CREDIT_GRANT = 1000;
 export declare const BASE_PRICING_PLANS: {
     readonly free: {
         readonly tier: "free";

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

@@ -2,6 +2,12 @@ export const WEEKLY_USAGE_WINDOW_DAYS = 7;
 export const BILLING_CURRENCIES = ["usd"];
 export const DEFAULT_BILLING_CURRENCY = "usd";
 export const CONTACT_SALES_URL = "https://cal.com/tim-scheuer-mxbib9/45";
+// Card-required free trial: every new signup starts a Stripe trial on the Starter
+// plan, gets TRIAL_CREDIT_GRANT credits (a value-demonstration budget sized to the
+// guided first outcome — NOT the full plan allowance), and converts to paid on
+// credit exhaustion or when the trial clock elapses, whichever comes first.
+export const TRIAL_PERIOD_DAYS = 7;
+export const TRIAL_CREDIT_GRANT = 1_000;
 export const BASE_PRICING_PLANS = {
     free: {
         tier: "free",

package/node_modules/@oxygen/shared/dist/cli-result.d.ts

@@ -30,6 +30,9 @@ export declare class OxygenError extends Error {
         exitCode?: number;
     });
 }
+export declare const CLI_EXIT_CODE_TABLE: Readonly<Record<number, string>>;
+export declare function exitCodeForErrorCode(code: string): number;
+export declare function exitCodeForOxygenError(error: OxygenError): number;
 export declare function success<T>(command: string, data: T, version?: string, minimumCliVersion?: string): CliSuccess<T>;
 export declare function failure(command: string, error: {
     code: string;

package/node_modules/@oxygen/shared/dist/cli-result.js

@@ -19,6 +19,71 @@ export class OxygenError extends Error {
         this.exitCode = options.exitCode ?? 1;
     }
 }
+// Reserved CLI exit codes, so shell agents can branch on failure class without
+// parsing the JSON envelope. Documented in `oxygen --help` and in the
+// `oxygen commands --json` manifest; treat as a stable contract.
+//
+//   0 ok · 1 unclassified error · 2 usage / input validation · 3 auth or CLI
+//   compatibility (not_authenticated, cli_update_required) · 4 not found ·
+//   5 provider / server failure · 6 rate limit (details.retry_after_seconds
+//   says how long to wait) · 7 approval / spend gate (re-run with --approved
+//   --max-credits <n>) · 8 timeout.
+export const CLI_EXIT_CODE_TABLE = {
+    0: "ok",
+    1: "unclassified error",
+    2: "usage / input validation",
+    3: "auth or CLI compatibility",
+    4: "not found",
+    5: "provider or server failure",
+    6: "rate limited (wait details.retry_after_seconds, then retry)",
+    7: "approval / spend gate (re-run with --approved --max-credits <n>)",
+    8: "timeout",
+};
+export function exitCodeForErrorCode(code) {
+    switch (code) {
+        case "not_authenticated":
+        case "unauthorized":
+        case "invalid_token":
+        case "cli_update_required":
+            return 3;
+        case "rate_limit_exceeded":
+            return 6;
+        case "max_credits_required":
+        case "approval_required":
+        case "spend_cap_required":
+        case "spend_cap_too_low":
+        case "insufficient_credits":
+        case "workspace_credit_cap_exceeded":
+        case "byok_requires_paid_plan":
+            return 7;
+        case "network_timeout":
+            return 8;
+        case "provider_error":
+        case "upstream_error":
+        case "internal_error":
+        case "server_error":
+            return 5;
+        default:
+            break;
+    }
+    if (code === "not_found" || code.endsWith("_not_found"))
+        return 4;
+    if (code === "timeout" || code.endsWith("_timeout"))
+        return 8;
+    if (code.startsWith("invalid_")
+        || code.startsWith("missing_")
+        || code === "unknown_fields"
+        || code === "validation_failed") {
+        return 2;
+    }
+    return 1;
+}
+// exitCode 1 is the legacy constructor default at ~170 OxygenError call sites;
+// treat a stored 1 as "unset" and derive the reserved code from the typed
+// error code instead. An explicit non-1 exitCode option always wins.
+export function exitCodeForOxygenError(error) {
+    return error.exitCode !== 1 ? error.exitCode : exitCodeForErrorCode(error.code);
+}
 export function success(command, data, version = OXYGEN_VERSION, minimumCliVersion = OXYGEN_MINIMUM_CLI_VERSION) {
     return {
         ok: true,

package/node_modules/@oxygen/shared/dist/deprecation-registry.d.ts

@@ -0,0 +1,12 @@
+export type DeprecationRegistryEntry = {
+    /** What is deprecated, precisely enough to grep for. */
+    surface: string;
+    /** OXYGEN_VERSION at which the surface became deprecated. */
+    deprecated_in: string;
+    /** Semver deadline, or "floor-bump" (see header). */
+    sunset_version: string;
+    /** Where the surface lives and what removal entails. */
+    note: string;
+};
+export declare const FLOOR_BUMP_SENTINEL = "floor-bump";
+export declare const DEPRECATION_REGISTRY: DeprecationRegistryEntry[];

package/node_modules/@oxygen/shared/dist/deprecation-registry.js

@@ -0,0 +1,58 @@
+// Deprecation sunset registry — the build-enforced list of deprecated agent
+// surfaces and when each one must actually be removed.
+//
+// Why this exists: deprecated aliases ("kept for old clients") historically
+// outlive every intention to remove them because nothing ever fails. The
+// registry inverts that: packages/shared/src/index.test.ts asserts that
+// OXYGEN_VERSION has NOT passed any entry's semver `sunset_version`. Once the
+// version crosses a sunset, the build goes red until the surface is deleted —
+// and removal means deleting the surface AND its registry entry in the same
+// PR.
+//
+// sunset_version values:
+//   - "1.x.y" semver — hard deadline, gated by the test.
+//   - "floor-bump"   — sentinel for surfaces that can only be removed when
+//     OXYGEN_MINIMUM_CLI_VERSION next rises past the clients that still use
+//     them (old CLIs on users' machines send/read these). The test validates
+//     the entry's shape but skips the version gate; whoever bumps the CLI
+//     floor must sweep the "floor-bump" entries in the same change.
+export const FLOOR_BUMP_SENTINEL = "floor-bump";
+export const DEPRECATION_REGISTRY = [
+    {
+        surface: "oxygen_templates_* MCP alias tools",
+        deprecated_in: "1.80.0",
+        sunset_version: "1.290.0",
+        note: "Deprecated alias tree of oxygen_prompts_* (packages/mcp-server/src/tools/" +
+            "prompt-template-tools.ts, prefix \"oxygen_templates\"). Removal: drop the " +
+            "alias prefix from the generated tools and the CLI `templates` alias " +
+            "command tree, then update the pinned tool counts.",
+    },
+    {
+        surface: "oxygen.linkedin-inbox widget alias",
+        deprecated_in: "1.226.0",
+        sunset_version: "1.290.0",
+        note: "Legacy alias of oxygen.unibox kept so MCP clients that cached " +
+            "ui://oxygen/linkedin-inbox keep resolving (packages/mcp-server/src/widgets/" +
+            "definitions.ts). Removal: delete the alias widget definition and any " +
+            "bindings that still point at it.",
+    },
+    {
+        surface: "CLI deepLink/deep_link response keys",
+        deprecated_in: "1.8.2",
+        sunset_version: FLOOR_BUMP_SENTINEL,
+        note: "web_url has been the canonical deep-link key since at least v1.8.2; " +
+            "/api/cli responses still duplicate it as deepLink/deep_link because " +
+            "CLIs at or below the current minimum version read the legacy keys. " +
+            "Remove the duplicated keys (and the CLI readers) when " +
+            "OXYGEN_MINIMUM_CLI_VERSION next rises past those clients.",
+    },
+    {
+        surface: "CLI --return/--org legacy flags",
+        deprecated_in: "1.0.0",
+        sunset_version: FLOOR_BUMP_SENTINEL,
+        note: "Legacy aliases of --return-mode/--org-id on `oxygen tools run` " +
+            "(packages/cli/src/index.ts); aliased since before versioned commits. " +
+            "Remove the flags and their request-body mappings when " +
+            "OXYGEN_MINIMUM_CLI_VERSION next rises past CLIs that send them.",
+    },
+];

package/node_modules/@oxygen/shared/dist/knowledge-markdown.d.ts

@@ -21,3 +21,28 @@ export type KnowledgePageRenderInput = {
  * verbatim with exactly one trailing newline.
  */
 export declare function renderKnowledgePageMarkdown(page: KnowledgePageRenderInput): string;
+export type ParsedKnowledgePageMarkdown = {
+    /** True when the file opened with a `---` frontmatter block (any keys). */
+    hasFrontmatter: boolean;
+    /** Raw scalar frontmatter values by key (tags stay in their `[a, b]` form here). */
+    frontmatter: Record<string, string>;
+    id: string | null;
+    slug: string | null;
+    type: string | null;
+    title: string | null;
+    status: string | null;
+    tags: string[] | null;
+    summary: string | null;
+    revision: number | null;
+    /** Body text below the frontmatter (whole file when none), no trailing newline. */
+    body: string;
+};
+/**
+ * Parse a mirror page file back into its fields — the inverse of
+ * renderKnowledgePageMarkdown, tolerant of human/agent edits (`oxygen knowledge
+ * push` runs this on locally edited files). Line-based like the renderer's
+ * contract: `key: value` pairs between `---` fences, tags as `[a, b]`. A file
+ * without a frontmatter block parses as pure body; a plain-markdown title is
+ * derived from the first `# heading` so brand-new local files can push.
+ */
+export declare function parseKnowledgePageMarkdown(contents: string): ParsedKnowledgePageMarkdown;

package/node_modules/@oxygen/shared/dist/knowledge-markdown.js

@@ -55,3 +55,77 @@ export function renderKnowledgePageMarkdown(page) {
     const body = (page.body ?? "").replace(/\r\n/g, "\n").replace(/\n+$/, "");
     return `${lines.join("\n")}\n${body}\n`;
 }
+/**
+ * Parse a mirror page file back into its fields — the inverse of
+ * renderKnowledgePageMarkdown, tolerant of human/agent edits (`oxygen knowledge
+ * push` runs this on locally edited files). Line-based like the renderer's
+ * contract: `key: value` pairs between `---` fences, tags as `[a, b]`. A file
+ * without a frontmatter block parses as pure body; a plain-markdown title is
+ * derived from the first `# heading` so brand-new local files can push.
+ */
+export function parseKnowledgePageMarkdown(contents) {
+    const text = contents.replace(/\r\n/g, "\n");
+    const lines = text.split("\n");
+    const parsed = {
+        hasFrontmatter: false,
+        frontmatter: {},
+        id: null,
+        slug: null,
+        type: null,
+        title: null,
+        status: null,
+        tags: null,
+        summary: null,
+        revision: null,
+        body: "",
+    };
+    let bodyStart = 0;
+    if (lines[0]?.trim() === "---") {
+        const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+        if (closing > 0) {
+            parsed.hasFrontmatter = true;
+            for (const line of lines.slice(1, closing)) {
+                const separator = line.indexOf(":");
+                if (separator <= 0)
+                    continue;
+                const key = line.slice(0, separator).trim();
+                if (!/^[A-Za-z0-9_-]+$/.test(key))
+                    continue;
+                parsed.frontmatter[key] = line.slice(separator + 1).trim();
+            }
+            bodyStart = closing + 1;
+            // The renderer emits exactly one blank line after the closing fence.
+            if (lines[bodyStart] === "")
+                bodyStart += 1;
+        }
+    }
+    parsed.body = lines.slice(bodyStart).join("\n").replace(/\n+$/, "");
+    const fm = parsed.frontmatter;
+    const str = (key) => {
+        const value = fm[key];
+        return value !== undefined && value !== "" ? value : null;
+    };
+    parsed.id = str("id");
+    parsed.slug = str("slug");
+    parsed.type = str("type");
+    parsed.title = str("title");
+    parsed.status = str("status");
+    parsed.summary = str("summary");
+    if (fm.tags !== undefined) {
+        const inner = fm.tags.replace(/^\[/, "").replace(/\]$/, "");
+        parsed.tags = inner
+            .split(",")
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0);
+    }
+    if (fm.revision !== undefined) {
+        const revision = Number.parseInt(fm.revision, 10);
+        parsed.revision = Number.isFinite(revision) ? revision : null;
+    }
+    if (!parsed.title) {
+        const heading = lines.slice(bodyStart).find((line) => /^#\s+\S/.test(line));
+        if (heading)
+            parsed.title = heading.replace(/^#\s+/, "").trim() || null;
+    }
+    return parsed;
+}

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.275.1";
+export declare const OXYGEN_VERSION = "1.284.3";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.275.1";
+export const OXYGEN_VERSION = "1.284.3";
 // Bump this only when deployed CLI/API contracts require a newer CLI.
 // 1.181.0: paid table action runs and background columns run require
 // approved=true in addition to max_credits; older CLIs cannot send the flag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.275.1",
+  "version": "1.284.3",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",