@oxygen-agent/cli 1.987.20 → 1.1010.1

package/dist/knowledge-mirror.d.ts

@@ -1,5 +1,5 @@
 export declare const GENERATED_MIRROR_FILE_HEADER = "<!-- generated by oxygen knowledge sync \u2014 local edits are overwritten -->";
-export type MirrorPageRecord = {
+type MirrorPageRecord = {
     id: string;
     revision: number;
     /** sha256 hex of the exact bytes the server rendered and this client wrote. */
@@ -98,7 +98,7 @@ 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 = {
+type MirrorPushCandidate = {
     slug: string;
     /** dirty = tracked page whose local bytes drifted; new = untracked local file. */
     kind: "dirty" | "new";

package/dist/runtime.d.ts

@@ -1,20 +1,5 @@
 declare const DEV_CLI_BINARY = "oxygen-dev";
 declare const PROD_CLI_BINARY = "oxygen";
-/**
- * Pins a terminal to a *host*, not to a profile label.
- *
- * `OXYGEN_PROFILE=default` was the guard prescribed after the last profile drift
- * (OXY-4081), and it cannot work: `default` is a name, and `login` writes an
- * `apiUrl` into whatever name is active — so the profile called `default` became
- * dev and the pin followed it there (OXY-4109). Every credit balance, ticket, and
- * whoami then came back from dev looking exactly like a healthy production answer.
- *
- * The invariant that a staff runbook actually needs is the host it dialed. Set
- * `OXYGEN_REQUIRE_API_URL=https://oxygen-agent.com` and any command that resolves
- * somewhere else refuses to run instead of quietly answering from the wrong
- * environment.
- */
-export declare const REQUIRED_API_URL_ENV = "OXYGEN_REQUIRE_API_URL";
 export type CliBinaryName = typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
 /**
  * Where a command actually sent its request, and what put it there.

package/dist/runtime.js

@@ -17,7 +17,7 @@ const PROD_CLI_BINARY = "oxygen";
  * somewhere else refuses to run instead of quietly answering from the wrong
  * environment.
  */
-export const REQUIRED_API_URL_ENV = "OXYGEN_REQUIRE_API_URL";
+const REQUIRED_API_URL_ENV = "OXYGEN_REQUIRE_API_URL";
 export function resolveCliBinaryName(env = process.env, argv = process.argv) {
     const explicit = normalizeBinaryName(env.OXYGEN_CLI_BINARY ?? env.OXYGEN_CLI_NAME);
     if (explicit)

package/dist/search-ai-filter-notice.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A charged search AI filter's run totals as one terminal line (ADR 0027,
+ * amendment 2026-09-25). `table-ingestions get` carries them under
+ * `ai_filter`; `table-ingestions wait` nests that response under
+ * `ingestionRun`. The blind baseline could not see what a filter kept and
+ * what it dropped, so the terminal says it next to the JSON.
+ *
+ * Matches and items the filter could not judge are both written to the table,
+ * so the line never sums them into one "kept": the blind acceptance
+ * (2026-09-25) read "kept 200, dropped 0" as 200 matches when 27 of them were
+ * never judged.
+ *
+ * Returns null unless the envelope carries run totals. The plan's and the dry
+ * run's `ai_filter` blocks are quotes without a `fetched` count, so they print
+ * nothing.
+ */
+export declare function formatSearchAiFilterTotalsNotice(data: unknown): string | null;

package/dist/search-ai-filter-notice.js

@@ -0,0 +1,38 @@
+import { isRecord } from "./util.js";
+/**
+ * A charged search AI filter's run totals as one terminal line (ADR 0027,
+ * amendment 2026-09-25). `table-ingestions get` carries them under
+ * `ai_filter`; `table-ingestions wait` nests that response under
+ * `ingestionRun`. The blind baseline could not see what a filter kept and
+ * what it dropped, so the terminal says it next to the JSON.
+ *
+ * Matches and items the filter could not judge are both written to the table,
+ * so the line never sums them into one "kept": the blind acceptance
+ * (2026-09-25) read "kept 200, dropped 0" as 200 matches when 27 of them were
+ * never judged.
+ *
+ * Returns null unless the envelope carries run totals. The plan's and the dry
+ * run's `ai_filter` blocks are quotes without a `fetched` count, so they print
+ * nothing.
+ */
+export function formatSearchAiFilterTotalsNotice(data) {
+    if (!isRecord(data))
+        return null;
+    const run = isRecord(data.ingestionRun) ? data.ingestionRun : data;
+    const totals = isRecord(run.ai_filter) ? run.ai_filter : null;
+    if (!totals || typeof totals.fetched !== "number")
+        return null;
+    const count = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+    const matched = count(totals.kept_matched ?? totals.matched);
+    const unjudged = count(totals.kept_unjudged ?? totals.unclassified);
+    const credits = count(totals.credits_charged);
+    const parts = [
+        `${matched} matched`,
+        `${unjudged} could not be judged (kept, marked unclassified)`,
+        `${count(totals.dropped)} dropped`,
+    ];
+    const unavailable = typeof totals.unavailable_reason === "string" && totals.unavailable_reason
+        ? `. The filter did not run on some pages: ${totals.unavailable_reason}`
+        : "";
+    return `AI filter: fetched ${count(totals.fetched)}: ${parts.join(", ")}${credits > 0 ? `; ${credits} credits` : ""}${unavailable}`;
+}

package/dist/session.d.ts

@@ -1,17 +1,17 @@
 export type SessionStepStatus = "pending" | "running" | "completed" | "error" | "skipped";
-export type SessionStep = {
+type SessionStep = {
     label: string;
     status: SessionStepStatus;
     startedAt: string | null;
     completedAt: string | null;
 };
-export type SessionStatusMessage = {
+type SessionStatusMessage = {
     id: string;
     message: string;
     stepIndex: number | null;
     createdAt: string;
 };
-export type SessionOutput = {
+type SessionOutput = {
     id: string;
     type: "csv" | "file" | "table";
     path: string | null;
@@ -54,3 +54,4 @@ export declare function addSessionOutput(input: {
 export declare function getSessionUsage(input: {
     sessionId?: string | null;
 }): Record<string, unknown>;
+export {};

package/dist/skills.d.ts

@@ -7,7 +7,8 @@ export type SkillsInstallOptions = {
     apiUrl?: string;
     agents?: string | string[];
     skill?: string;
-    project?: boolean;
+    /** `true` for the current directory, or the project directory to install into. */
+    project?: boolean | string;
     copy?: boolean;
 };
 export type SkillsListOptions = {
@@ -33,12 +34,6 @@ export type AutomaticSkillsInstallResult = {
         details?: unknown;
     };
 };
-export type SkillsAccessResponse = {
-    base_url: string;
-    index_url: string;
-    expires_at: string;
-    skills_version?: string;
-};
 export type SkillsInstallSource = {
     authenticated: boolean;
     /** Base URL handed to `npx skills add` (tokenized when authenticated). */
@@ -72,6 +67,12 @@ options: SkillsInstallOptions, runtime?: {
     execFileSync?: ExecFileSyncLike;
     spawnSync?: SpawnSyncLike;
 } & SkillsSourceRuntime): Promise<Record<string, unknown>>;
+/**
+ * `--project` is a bare flag for the current directory, or names the project
+ * directory to install into. `--project .` used to fail with "too many
+ * arguments" (2026-09-16 blind baseline) because the flag took no value.
+ */
+export declare function resolveSkillProjectDir(project: boolean | string | undefined): string | null;
 export declare function runAutomaticSkillsInstall(options?: {
     apiUrl?: string;
     env?: NodeJS.ProcessEnv;

package/dist/skills.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { OxygenError, inferUserCapabilityRoute, serializeCapabilityRoute, toFailure, } from "@oxygen/shared";
+import { OxygenError, errorMessage, inferUserCapabilityRoute, serializeCapabilityRoute, toFailure, } from "@oxygen/shared";
 import { defaultApiUrl, loadCredentials, normalizeApiUrl } from "./credentials.js";
 import { requestOxygen } from "./http-client.js";
 import { isRecord, readOption } from "./util.js";
@@ -226,7 +226,8 @@ options, runtime = {}) {
     const env = runtime.env ?? process.env;
     const platform = runtime.platform ?? process.platform;
     const spawn = runtime.spawnSync ?? wrapExecFileSync(runtime.execFileSync) ?? spawnSync;
-    const installLocations = resolveSkillInstallLocations(agents, options.project === true, env);
+    const projectDir = resolveSkillProjectDir(options.project);
+    const installLocations = resolveSkillInstallLocations(agents, projectDir, env);
     // The vendored installer writes immediately once spawned. Tell humans and
     // agents the exact destination first so a default global install is never a
     // surprise, while keeping stdout as one stable JSON envelope under --json.
@@ -268,6 +269,8 @@ options, runtime = {}) {
             const result = spawn(invocation.executable, invocation.args, {
                 encoding: "utf8",
                 env,
+                // A project install lands relative to the installer's working directory.
+                ...(projectDir ? { cwd: projectDir } : {}),
                 stdio: ["ignore", "pipe", "pipe"],
                 windowsHide: true,
                 ...(platform === "win32" ? { windowsVerbatimArguments: true } : {}),
@@ -342,11 +345,25 @@ options, runtime = {}) {
         summary: summarizeInstallOutcome(agents.length, skippedAgents.length, 0),
     };
 }
-function resolveSkillInstallLocations(agents, project, env) {
+/**
+ * `--project` is a bare flag for the current directory, or names the project
+ * directory to install into. `--project .` used to fail with "too many
+ * arguments" (2026-09-16 blind baseline) because the flag took no value.
+ */
+export function resolveSkillProjectDir(project) {
+    if (project === true)
+        return process.cwd();
+    if (typeof project === "string" && project.trim())
+        return resolve(project.trim());
+    return null;
+}
+function resolveSkillInstallLocations(agents, projectDir, env) {
+    const project = projectDir !== null;
+    const base = projectDir ?? process.cwd();
     const projectRoots = {
-        codex: resolve(".agents", "skills"),
-        "claude-code": resolve(".claude", "skills"),
-        cursor: resolve(".agents", "skills"),
+        codex: resolve(base, ".agents", "skills"),
+        "claude-code": resolve(base, ".claude", "skills"),
+        cursor: resolve(base, ".agents", "skills"),
     };
     const globalRoots = {
         codex: join(env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "skills"),
@@ -356,7 +373,7 @@ function resolveSkillInstallLocations(agents, project, env) {
     const roots = project ? projectRoots : globalRoots;
     return agents.map((agent) => ({
         agent,
-        path: roots[agent] ?? (project ? resolve(".agents", "skills") : join(homedir(), ".agents", "skills")),
+        path: roots[agent] ?? (project ? resolve(base, ".agents", "skills") : join(homedir(), ".agents", "skills")),
     }));
 }
 /**
@@ -448,9 +465,6 @@ function stagingFailure(stage, details) {
         exitCode: 1,
     });
 }
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 // Best-effort resolution of a skill's declared prerequisite skills from the
 // index. Any failure (unreachable index, parse error, unknown skill) yields no
 // dependencies so a dependency lookup can never block or fail an install.
@@ -779,27 +793,51 @@ function scoreSkill(skill, tokens, recommendedSkills) {
         score += 400 - (routeIndex * 20);
     return score;
 }
+/**
+ * Rank a skill's documents against the query tokens.
+ *
+ * An EXACT hit on a provider name, a path segment, or a tag outranks an
+ * incidental substring. Flat `includes` scoring made a query that literally
+ * names a provider lose to an unrelated document that merely contains the
+ * letters: measured 2026-09-21, `skills search "hubspot import segment
+ * do-not-contact suppression"` returned `provider-runbooks/bettercontact.md`
+ * and not `provider-runbooks/hubspot.md`, because "contact" is a substring of
+ * "bettercontact" and the alphabetical tie-break did the rest. A blind
+ * acceptance run lost its whole HubSpot fallback to that.
+ */
 function matchingSkillDocuments(skill, tokens) {
     if (tokens.length === 0)
         return [];
     return skill.documents
         .map((document) => ({
         document,
-        score: tokens.reduce((total, token) => {
-            const text = [
-                document.path,
-                document.title ?? "",
-                document.kind ?? "",
-                ...document.tags,
-                ...document.providers,
-            ].join(" ").toLowerCase();
-            return total + (text.includes(token) ? 1 : 0);
-        }, 0),
+        score: scoreSkillDocument(document, tokens),
     }))
         .filter((entry) => entry.score > 0)
         .sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path))
         .map((entry) => entry.document);
 }
+function scoreSkillDocument(document, tokens) {
+    const exact = new Set([
+        ...document.providers.map((value) => value.toLowerCase()),
+        ...document.tags.map((value) => value.toLowerCase()),
+        // Path segments without the extension: "provider-runbooks/hubspot.md" ->
+        // "provider", "runbooks", "hubspot".
+        ...document.path.toLowerCase().replace(/\.[a-z0-9]+$/, "").split(/[^a-z0-9]+/),
+    ].filter(Boolean));
+    const substring = [
+        document.path,
+        document.title ?? "",
+        document.kind ?? "",
+        ...document.tags,
+        ...document.providers,
+    ].join(" ").toLowerCase();
+    return tokens.reduce((total, token) => {
+        if (exact.has(token))
+            return total + 5;
+        return total + (substring.includes(token) ? 1 : 0);
+    }, 0);
+}
 function inspectSkillsInstaller() {
     const invocation = resolveCmdShimInvocation("npx", ["--version"], process.platform, process.env);
     const result = spawnSync(invocation.executable, invocation.args, {

package/dist/transcript.d.ts

@@ -1,4 +1,4 @@
-export type TranscriptSource = "claude_code" | "codex" | "cursor" | "file";
+type TranscriptSource = "claude_code" | "codex" | "cursor" | "file";
 export type CapturedTranscript = {
     source: TranscriptSource;
     session_id: string | null;
@@ -19,3 +19,4 @@ export declare class TranscriptCaptureError extends Error {
 }
 export declare function captureCurrentTranscript(options?: CaptureOptions): CapturedTranscript | null;
 export declare function collectFeedbackEnvironment(): Record<string, string>;
+export {};

package/dist/util.d.ts

@@ -1,3 +1,12 @@
+export { isRecord } from "@oxygen/shared";
 export declare function readOption(value: string | undefined): string | null;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * A flag whose ABSENCE and whose EMPTY value mean different things: absent
+ * leaves the field alone, `""` clears it. `readOption` folds both into `null`,
+ * which is how `crm tasks update --title x` used to send `priority: null,
+ * due_at: null, body: null, assignee_actor_id: null` and wipe a task's deadline
+ * and priority on every rename (dev, 2026-09-22) — and `crm notes update --pin`
+ * cleared the title the same way.
+ */
+export declare function readClearableOption(value: string | undefined): string | null | undefined;
 export declare function readErrorMessage(error: unknown): string;

package/dist/util.js

@@ -1,8 +1,20 @@
+export { isRecord } from "@oxygen/shared";
 export function readOption(value) {
     return typeof value === "string" && value.trim() ? value.trim() : null;
 }
-export function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+/**
+ * A flag whose ABSENCE and whose EMPTY value mean different things: absent
+ * leaves the field alone, `""` clears it. `readOption` folds both into `null`,
+ * which is how `crm tasks update --title x` used to send `priority: null,
+ * due_at: null, body: null, assignee_actor_id: null` and wipe a task's deadline
+ * and priority on every rename (dev, 2026-09-22) — and `crm notes update --pin`
+ * cleared the title the same way.
+ */
+export function readClearableOption(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
 }
 export function readErrorMessage(error) {
     return error instanceof Error ? error.message : "unknown error";