@oxygen-agent/cli 1.1014.19 → 1.1014.69

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.1014.19
+Version: 1.1014.69

package/dist/command-manifest.js

@@ -306,7 +306,7 @@ export function searchCommandManifest(manifest, query, requestedLimit = DEFAULT_
         commands: matches.slice(0, limit).map(({ command, score }) => ({
             name: command.name,
             group: command.group,
-            description: command.description,
+            description: (command.description.split(/(?<=[.!?])\s/)[0] ?? command.description).slice(0, 180),
             spends_credits: command.spends_credits,
             mutates: command.mutates,
             destructive: command.destructive,

package/dist/help.js

@@ -126,6 +126,17 @@ const HELP_GROUPS = [
 ];
 const FALLBACK_HEADING = "Other commands:";
 export function applyOxygenHelp(program, binaryName) {
+    program.option("--help-full", "Show expanded command and option descriptions.");
+    const configure = (command) => {
+        command.configureHelp({
+            commandDescription: (cmd) => shortHelpDescription(cmd.description()),
+            subcommandDescription: (cmd) => shortHelpDescription(cmd.description()),
+            optionDescription: (option) => shortHelpDescription(option.description),
+        });
+        for (const child of command.commands)
+            configure(child);
+    };
+    configure(program);
     const headingByCommand = new Map();
     for (const group of HELP_GROUPS) {
         for (const name of group.commands)
@@ -140,6 +151,7 @@ export function applyOxygenHelp(program, binaryName) {
     program.addHelpText("before", [
         "",
         "Agent quickstart:",
+        "  Help is concise; --help-full or commands get <name> --json retains complete grammar.",
         `  1. ${binaryName} login                      connect this terminal (or set OXYGEN_API_KEY)`,
         `     ${binaryName} whoami --summary-json     confirm the active workspace and identity (0 credits)`,
         // `login` auto-installs the skills, but an agent authenticating with
@@ -171,6 +183,12 @@ export function applyOxygenHelp(program, binaryName) {
     ].join("\n"));
     program.addHelpText("afterAll", `\nExit codes: ${exitCodeLine}`);
 }
+function shortHelpDescription(description) {
+    if (process.argv.includes("--help-full"))
+        return description;
+    const first = description.split(/(?<=[.!?])\s/)[0] ?? description;
+    return first.length <= 180 ? first : `${first.slice(0, 177)}…`;
+}
 /**
  * Turn commander's own edit-distance suggester on for EVERY command.
  *
@@ -443,7 +461,9 @@ function buildUnknownCommandHint(parent, path, token) {
     // command.
     const prefixMatches = names.filter((name) => name.startsWith(lower));
     const suggestion = synonym ?? (prefixMatches.length === 1 ? prefixMatches[0] : null);
-    const helpLine = `Run \`${path} --help\` for the ${names.length} subcommands of \`${path}\`.`;
+    const query = path.split(" ").slice(1).concat(token).join(" ");
+    const quotedQuery = `'${query.replace(/'/g, "'\\''")}'`;
+    const helpLine = `Find the command with \`${path.split(" ")[0]} commands search ${quotedQuery} --json\`; hydrate the selected name with \`${path.split(" ")[0]} commands get <name> --json\`.`;
     return suggestion
         ? `Hint: \`${path}\` has no \`${token}\`. Did you mean \`${path} ${suggestion}\`? ${helpLine}`
         : `Hint: \`${path}\` has no \`${token}\`. ${helpLine}`;

package/dist/index.js

@@ -20,6 +20,7 @@ import { applyOxygenHelp, argvRequestsJson, commanderUsageFailure, commandNameFo
 import { homeStandupMarksSeen } from "./home-standup.js";
 import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
 import { formatInboxNeedsReplyNotice } from "./inbox-needs-reply-notice.js";
+import { serializeCliJson, writeExclusiveJson } from "./json-output.js";
 import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, listLocalMirrors, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
 import { registerKnowledgeRepositoryCommands } from "./knowledge-repository-commands.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
@@ -42,6 +43,7 @@ import { registerVisualCommands } from "./visual-commands.js";
 import { WHATSAPP_ACCOUNT_FLAGS, whatsappAccountQuery } from "./whatsapp-account-flags.js";
 import { formatWorkflowPlanLimitNotices } from "./workflow-plan-limit-notices.js";
 import { WORKFLOW_RUN_LIST_FLAG_OVERLAY, readWorkflowRunListFlags } from "./workflow-run-list-flags.js";
+import { registerWorkspaceSkillCommands } from "./workspace-skill-commands.js";
 import { addProviderLimitFlags, addSuppressionListFlags, providerLimitBody, providerLimitQuery, suppressionListQuery } from "./workspace-utility-flags.js";
 import { isRecipeDefinition } from "@oxygen/recipe-sdk";
 import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, COLLAB_GATE_KINDS, COLLAB_GATE_PROSE, COLLAB_SUBJECT_KINDS, COLLAB_SUBJECT_KINDS_PROSE, COLLAB_SUBJECT_LABELS, COLLAB_SUBJECT_PROSE, GATE_KIND_SUBJECTS, describeWorkflowStatusChange, formatCellForDisplay, formatCopilotPlanDuration, formatCopilotPlanSeconds, formatPublicBudgetScopes, SUBJECT_PATH_FORMS_PROSE, formatSubjectPath, exitCodeForOxygenError, parseSubjectPath, parseSubjectRef, parseWorkflowStatusChange, chunk, isVersionGreater, isVersionLess, KNOWLEDGE_BOOTSTRAP_MAX_CREDITS, MAX_CLI_JSON_BODY_BYTES, MAX_MCP_TOOL_NAME_LENGTH, normalizeCopilotPlanStepStatus, OXYGEN_CAPABILITY_ROUTES, OXYGEN_VERSION, OxygenError, getCapabilityRouteMatch, inferUserCapabilityRoute, parseKnowledgePageMarkdown, PLAN_LIMITS, serializeCapabilityRoute, sleep, success, TAG_KINDS_PROSE, toFailure, workflowMcpToolName, } from "@oxygen/shared";
@@ -65,6 +67,7 @@ import { SEQUENCE_LIST_PROJECTION_CONTRACT } from "@oxygen/shared/contracts/sequ
 import { TABLE_FEED_UPDATE_CONTRACT, tableFeedUpdateIssues } from "@oxygen/shared/contracts/table-feed-update";
 import { TABLE_LIST_QUERY_CONTRACT, tableListQueryParams } from "@oxygen/shared/contracts/table-list";
 import { TABLE_QUERY_GRID_CONTRACT } from "@oxygen/shared/contracts/table-query-grid";
+import { TABLE_QUERY_CLI_DEFAULT_LIMIT, TABLE_QUERY_CLI_DEFAULT_MAX_CHARS, tableQueryRawResultFits, tableQueryRawRecovery } from "@oxygen/shared/contracts/table-query-raw";
 import { WHATSAPP_ACCOUNTS_READ_CONTRACT } from "@oxygen/shared/contracts/whatsapp-reads";
 import { WORKFLOW_RUN_LIST_CONTRACT, workflowRunListQueryParams } from "@oxygen/shared/contracts/workflow-run-list";
 import { COPILOT_ASK_USER_TOOL_NAME, normalizeCopilotQuestions } from "@oxygen/shared/copilot-questions";
@@ -79,6 +82,7 @@ import { TAG_COLORS } from "@oxygen/shared/select-options";
 import { SEQUENCE_LIFECYCLES, sequenceDisplayStatus } from "@oxygen/shared/sequence-lifecycle";
 import { lookupColumnDataType } from "@oxygen/shared/table-field-types";
 import { FILTER_TREE_OPERATORS } from "@oxygen/shared/table-filter-operators";
+import { tableRunSummary } from "@oxygen/shared/table-run-summary";
 import { assertRecipeBundleSafe, assertPortableWorkflowDefinition, assertWorkflowGraphManifest, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowGraphManifest, isWorkflowManifest, hashPortableWorkflowGraphManifest, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, } from "@oxygen/workflows";
 import { Command, CommanderError, Option } from "commander";
 import { execFileSync } from "node:child_process";
@@ -435,7 +439,7 @@ const RECIPE_ESBUILD_NODE_PATHS = [
     resolve(CLI_MODULE_DIR, "../../../node_modules"),
 ];
 function writeJson(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    process.stdout.write(serializeCliJson(value, process.argv.includes("--pretty")));
 }
 function linkBar(coverage, width = 36) {
     const filled = Math.max(0, Math.min(width, Math.round(coverage * width)));
@@ -3668,6 +3672,7 @@ export function createProgram() {
         .name(binaryName)
         .description("Revenue infrastructure for B2B startups — agent-operated GTM: tables, enrichment, sequences, workflows, CRM, knowledge. Everything here also runs in the web app and over MCP; every state-changing action returns a web_url deep-link.")
         .version(OXYGEN_VERSION)
+        .option("--pretty", "Indent JSON output (default: compact JSON).")
         .option("--profile <name>", "Use a stored CLI profile for this command.")
         .option("--org <organization>", "Use an organization id, Clerk org id, or slug for this command.");
     program.hook("preAction", (_root, selected) => {
@@ -7237,10 +7242,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }))
         .addCommand(addContractFlags(new Command("query"), TABLE_QUERY_GRID_CONTRACT, {
         format: { valueName: "<format>", help: "Grid cell previews/state: default 50, cap 200, optional stats/fill/window. Omit for raw filters, fields, search, sorts or offsets." },
+        max_chars: { help: "Maximum compact JSON envelope characters for raw or grid reads (1,000-100,000). Raw defaults to 12,000." },
     })
         .description("Read raw Table rows or --format grid cell previews/state with grid.nextCursor, in a JSON envelope. Use tables preview --summary-only for fill rates; tables export <table> --format table renders raw rows. Grid supports stats/fill/window options and refuses raw selectors.")
         .argument("<table>", "Table id or slug.")
-        .option("--limit <n>", "Raw: default 100, native cap 2000. Grid: default 50, cap 200.")
+        .option("--limit <n>", "Raw: default 20, native cap 2000; --full restores default 100. Grid: default 50, cap 200.")
         .option("--cursor <cursor>", "Pagination cursor returned by a previous query. Walks forward one page at a time; mutually exclusive with --offset.")
         .option("--offset <n>", "Skip this many rows and start there — jump straight to a row without paging to it. Mutually exclusive with --cursor.")
         .option("--fields <columns>", "Comma-separated column keys or ids to include.")
@@ -7250,14 +7256,21 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--formula-values <mode>", "Formula filters are refused by default because displayed formulas are evaluated live. Refresh the formula's stored cells with `columns run <table> <column> --force` (0 credits), then pass 'materialized'; filtering uses that stored snapshot and returns a freshness note. A fill-empty field a bundle adds (definition fill: \"empty\", such as Headcount or Job title) is stored, not live: its cell is the value, so 'materialized' filters it exactly.")
         .option("--sort-json <json>", "Ordered sort rules, e.g. '[{\"columnKey\":\"_created_at\",\"direction\":\"desc\"}]'. Earlier rules dominate. Mutually exclusive with --filter-json.")
         .option("--no-system-fields", "Omit _row_id, _created_at, and _updated_at from returned rows (included by default).")
+        .option("--full", "Read legacy full rows without the default character limit.")
+        .option("--output <path>", "Write full JSON for this page to a new local file; print a small receipt.")
         .option("--json", "Print a JSON envelope.")
         .action(async (table, options) => {
-        await handleAsyncAction("tables query", options, () => {
+        await handleAsyncAction("tables query", options, async () => {
             const gridArgs = readContractFlags(options, TABLE_QUERY_GRID_CONTRACT);
-            if (gridArgs.format !== "grid" && Object.keys(gridArgs).length > 0) {
+            if (gridArgs.format !== "grid" && Object.keys(gridArgs).some((key) => key !== "max_chars")) {
                 throw new OxygenError("invalid_request", "Grid options require --format grid.", { exitCode: 1 });
             }
-            const limit = readPositiveInt(options.limit);
+            const full = options.full || Boolean(options.output);
+            if (full && options.format === "grid")
+                throw new OxygenError("invalid_request", "--full/--output require raw rows; omit --format grid.", { exitCode: 2 });
+            const limit = readPositiveInt(options.limit) ?? (options.format !== "grid" && !full ? TABLE_QUERY_CLI_DEFAULT_LIMIT : undefined);
+            if (options.format !== "grid" && !full && gridArgs.max_chars === undefined)
+                gridArgs.max_chars = TABLE_QUERY_CLI_DEFAULT_MAX_CHARS;
             const filters = readFilterJsonOption(options.filterJson);
             const filterTree = readJsonObjectOption(options.filterTreeJson);
             const formulaValues = readFormulaValuesOption(options.formulaValues);
@@ -7276,7 +7289,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 readOption(options.search) || formulaValues || sorts?.length || (offset !== undefined && offset > 0))) {
                 throw new OxygenError("invalid_request", '--format grid takes only table, --limit, --cursor and optional --include-stats/--include-fill; omit --format for filters, fields, search, sorts or offsets.', { exitCode: 1 });
             }
-            return requestOxygen("/api/cli/tables/query", {
+            const data = await requestOxygen("/api/cli/tables/query", {
                 method: "POST",
                 body: {
                     table,
@@ -7293,6 +7306,17 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     ...(options.systemFields === false ? { include_system_fields: false } : {}),
                 },
             });
+            // Enforce the window even against an older compatible serving API.
+            if (options.format !== "grid" && !tableQueryRawResultFits(data, typeof gridArgs.max_chars === "number" ? gridArgs.max_chars : undefined)) {
+                const firstRow = Array.isArray(data.rows) ? data.rows[0] : undefined;
+                throw new OxygenError("table_query_result_too_large", "Table rows exceed the requested result window.", {
+                    details: { max_chars: gridArgs.max_chars, ...tableQueryRawRecovery(table, typeof firstRow?._row_id === "string" ? firstRow._row_id : undefined) }, exitCode: 2,
+                });
+            }
+            if (!options.output)
+                return data;
+            const output = await writeExclusiveJson(options.output, success("tables query", data), process.argv.includes("--pretty"));
+            return { output, returned_count: data.returned_count ?? data.returnedCount, total_count: data.total_count ?? data.totalCount, hasMore: data.hasMore, nextCursor: data.nextCursor, web_url: data.web_url };
         });
     }))
         .addCommand(new Command("preview")
@@ -10656,11 +10680,17 @@ Examples:
         .addCommand(new Command("functions")
         .description("List every formula function (name, signature, examples), the operator grammar, and the expression_notes that a signature cannot teach (bare column keys, string escapes, no regex flags, read-time evaluation). The same language powers formula columns and --run-condition gates.")
         .option("--category <category>", "Filter by category: logic, string, number, date, url_email, array, json, null_handling, cross_row.")
+        .option("--query <text>", "Find functions by name, signature or description.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("formulas functions", options, () => {
             const category = readOption(options.category);
-            const query = category ? `?category=${encodeURIComponent(category)}` : "";
+            const params = new URLSearchParams();
+            if (category)
+                params.set("category", category);
+            if (readOption(options.query))
+                params.set("query", readOption(options.query));
+            const query = params.size ? `?${params.toString()}` : "";
             return requestOxygen(`/api/cli/tables/formulas/functions${query}`, { method: "GET" });
         });
     }))
@@ -10739,9 +10769,11 @@ Examples:
         .addCommand(new Command("get")
         .description("Get one durable table action run. For a Function run, selection.rowIds are rows of the Function's execution table, not the calling table; list the calling table's rows it wrote with `tables query <caller> --filter-tree-json` on the Function column's \"action_run_id\" path.")
         .argument("<run_id>", "Table action run UUID or parent workspace run UUID.")
+        .option("--full", "Read the full run, including stored inputs and metadata.")
         .option("--json", "Print a JSON envelope.")
         .action(async (runId, options) => {
-        await handleAsyncAction("table-runs get", options, () => requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}`));
+        await handleAsyncAction("table-runs get", options, () => requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}?view=${options.full ? "full" : "summary"}`)
+            .then((run) => options.full ? run : tableRunSummary(run)));
     }))
         .addCommand(new Command("items")
         .description("List row items for a durable table action run. For a Function run, list the calling table's rows it wrote with `tables query <caller> --filter-tree-json` on the Function column's \"action_run_id\" path instead of joining items.")
@@ -10766,6 +10798,7 @@ Examples:
         .argument("<run_id>", "Table action run UUID or parent workspace run UUID.")
         .option("--timeout-seconds <n>", "Maximum time to wait. Defaults to 600.")
         .option("--interval-seconds <n>", "Polling interval. Defaults to 5.")
+        .option("--full", "Return the full completed run instead of a progress summary.")
         .option("--json", "Print a JSON envelope.")
         .action(async (runId, options) => {
         await handleAsyncAction("table-runs wait", options, () => waitForTableActionRun(runId, options));
@@ -16689,10 +16722,11 @@ Examples:
         .option("--status <status>", "Filter by enrollment status (pending, active, waiting_connection, waiting_signal, replied, completed, stopped, failed, excluded). pending = enrolled, not started (next_due not_started); waiting_connection = invite sent, not accepted yet. Status is the lead's progress, not its invite: use --invite accepted for the leads that accepted.")
         .option("--step <n>", "Only leads currently on this step (0-based index, as in the sequence's steps).")
         .option("--invite <state>", "Only leads in this LinkedIn invite state: accepted (invited and connected), pending (invited, not accepted yet) or not_invited (no invite: already connected before, suppressed or email-only).")
-        .option("--view <view>", "full (default, every enrollment field) or compact (one short row per lead with next_due in words and local time).")
+        .option("--view <view>", "compact (default) or full (every enrollment field) (one short row per lead with next_due in words and local time).")
         .option("--order <order>", "created (default) or due: soonest next_due first, then waiting leads by gives_up_at, then leads with nothing due.")
         .option("--limit <n>", "Maximum enrollments to return (1-500).")
         .option("--offset <n>", "Skip this many enrollments; pass next_offset from the previous page to continue.")
+        .option("--full", "Read every enrollment field (same as --view full).")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences enrollments", options, () => {
@@ -16706,7 +16740,7 @@ Examples:
             const invite = readOption(options.invite);
             if (invite)
                 params.set("invite", invite);
-            const view = readOption(options.view);
+            const view = options.full ? "full" : readOption(options.view) ?? "compact";
             if (view)
                 params.set("view", view);
             const order = readOption(options.order);
@@ -20456,7 +20490,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
     })));
     program
         .command("skills")
-        .description("Agent skill discovery and installation commands.")
+        .description("Find and install Oxygen guides, or create and import private workspace skills with skills workspace.")
         .addCommand(new Command("list")
         .description("List Oxygen agent skills available from the hosted skill index.")
         .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
@@ -20508,6 +20542,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
     registerConnectorsCommands(program, handleAsyncAction);
     registerSettingsCommands(program, handleAsyncAction);
     registerCrmSupportFlags(program);
+    registerWorkspaceSkillCommands(program, handleAsyncAction);
     registerCustomerOperationCommands(program, handleAsyncAction);
     registerCrmFileReadCommands(program, handleAsyncAction);
     // After the register* helpers: help groups are assigned to the commands that
@@ -24314,12 +24349,12 @@ function buildGetSurfaceRunWaitConfig(params) {
         defaultTimeoutSeconds: params.defaultTimeoutSeconds,
         defaultIntervalSeconds: params.defaultIntervalSeconds,
         retryTransientNetworkErrors: params.retryTransientNetworkErrors === true,
-        fetchRun: (signal) => requestOxygen(`${params.endpoint}/${encodeURIComponent(params.runId)}`, signal ? { signal } : {}),
+        fetchRun: (signal) => requestOxygen(`${params.endpoint}/${encodeURIComponent(params.runId)}${params.view ? `?view=${params.view}` : ""}`, signal ? { signal } : {}),
         isTerminal: params.isTerminal,
         shapeTerminal: (run, status, polls, elapsedMs) => {
             const webUrl = readRecordString(run, "web_url");
             return {
-                [params.runKey]: run,
+                [params.runKey]: params.view === "summary" ? tableRunSummary(run) : run,
                 [params.runIdKey]: readRecordString(run, "id") ?? params.runId,
                 status,
                 terminal: true,
@@ -24372,6 +24407,7 @@ function waitForTableActionRun(runId, options) {
     return waitForCliRun(buildGetSurfaceRunWaitConfig({
         runId,
         endpoint: "/api/cli/table-action-runs",
+        view: options.full ? "full" : "summary",
         requestedTimeoutSeconds: options.timeoutSeconds,
         requestedIntervalSeconds: options.intervalSeconds,
         defaultTimeoutSeconds: TABLE_ACTION_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS,
@@ -30623,7 +30659,7 @@ beginCliDiagnostics();
 maybeScheduleBackgroundUpdate();
 const program = createProgram();
 installCommanderExitOverride(program);
-const argv = withoutHelpForUnknownCommand(program, process.argv);
+const argv = withoutHelpForUnknownCommand(program, process.argv.map((arg) => arg === "--help-full" ? "--help" : arg));
 setCliDiagnosticOperation(commandNameForArgv(program, argv.slice(2)));
 try {
     await program.parseAsync(argv);

package/dist/json-output.d.ts

@@ -0,0 +1,3 @@
+export declare function serializeCliJson(value: unknown, pretty?: boolean): string;
+/** Own only the newly created file; preserve an existing destination on every failure. */
+export declare function writeExclusiveJson(path: string, value: unknown, pretty?: boolean): Promise<string>;

package/dist/json-output.js

@@ -0,0 +1,33 @@
+import { open, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared/cli-result";
+export function serializeCliJson(value, pretty = false) {
+    return `${JSON.stringify(value, null, pretty ? 2 : undefined)}\n`;
+}
+/** Own only the newly created file; preserve an existing destination on every failure. */
+export async function writeExclusiveJson(path, value, pretty = false) {
+    const destination = resolve(path);
+    const serialized = serializeCliJson(value, pretty);
+    let handle;
+    try {
+        handle = await open(destination, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new OxygenError("output_exists", "Output file already exists. Choose a new path.", { exitCode: 2 });
+        }
+        throw new OxygenError("output_write_failed", "Unable to create the output file. Check the path and permissions.", { exitCode: 2 });
+    }
+    try {
+        await handle.writeFile(serialized, "utf8");
+        await handle.close();
+        return destination;
+    }
+    catch {
+        await handle.close().catch(() => undefined);
+        const removed = await unlink(destination).then(() => true, () => false);
+        throw new OxygenError("output_write_failed", removed
+            ? "Unable to write the output file. The partial file was removed."
+            : "Unable to write or remove the partial output file. Check the destination before retrying.", { exitCode: 2 });
+    }
+}

package/dist/workspace-skill-commands.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { type WorkspaceSkillFile } from "@oxygen/shared/workspace-skills";
+/** Never follow symlinks or read binary files out of a local skill folder. */
+export declare function readWorkspaceSkillDirectory(directory: string): Promise<WorkspaceSkillFile[]>;
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+export declare function registerWorkspaceSkillCommands(program: Command, handle: Handle): void;
+export {};

package/dist/workspace-skill-commands.js

@@ -0,0 +1,134 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { authorWorkspaceSkill, parseWorkspaceSkillBundle, WORKSPACE_SKILL_MAX_BYTES, WORKSPACE_SKILL_MAX_FILES, WORKSPACE_SKILL_MAX_FILE_BYTES, } from "@oxygen/shared/workspace-skills";
+import { requestOxygen } from "./http-client.js";
+/** Never follow symlinks or read binary files out of a local skill folder. */
+export async function readWorkspaceSkillDirectory(directory) {
+    const root = resolve(directory);
+    const files = [];
+    let bytes = 0;
+    const visit = async (relative, depth) => {
+        if (depth > 15)
+            throw new OxygenError("invalid_workspace_skill", "Skill directory nesting exceeds 15 levels.", { exitCode: 2 });
+        const path = join(root, relative);
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            throw new OxygenError("invalid_workspace_skill", "Skill imports do not follow symbolic links.", { exitCode: 2 });
+        if (stat.isDirectory()) {
+            for (const child of (await readdir(path)).sort()) {
+                if ([".git", "node_modules", ".DS_Store"].includes(child))
+                    continue;
+                await visit(relative ? `${relative}/${child}` : child, depth + 1);
+            }
+            return;
+        }
+        if (!stat.isFile() ||
+            stat.size > WORKSPACE_SKILL_MAX_FILE_BYTES ||
+            files.length >= WORKSPACE_SKILL_MAX_FILES ||
+            bytes + stat.size > WORKSPACE_SKILL_MAX_BYTES) {
+            throw new OxygenError("invalid_workspace_skill", "Import supports at most 50 text files, 120 KB per file and 1 MB total.", { exitCode: 2 });
+        }
+        const buffer = await readFile(path);
+        bytes += buffer.byteLength;
+        let content;
+        try {
+            content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer);
+        }
+        catch {
+            throw new OxygenError("invalid_workspace_skill", `File ${relative} is not UTF-8 text.`, { exitCode: 2 });
+        }
+        files.push({ path: relative, content });
+    };
+    await visit("", 0);
+    return files;
+}
+export function registerWorkspaceSkillCommands(program, handle) {
+    const skills = program.commands.find((command) => command.name() === "skills");
+    const workspace = skills
+        .command("workspace")
+        .description("Create, upload, find and edit private workspace skills in Knowledge.");
+    workspace
+        .command("create")
+        .description("Write a private workspace skill. Stores instructions; 0 credits.")
+        .requiredOption("--name <name>", "Lowercase-hyphen skill name.")
+        .requiredOption("--description <text>", "When to use this skill.")
+        .requiredOption("--instructions <text>", "Instructions to save.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options, command) => handle("skills workspace create", { json: command.optsWithGlobals().json === true }, async () => {
+        authorWorkspaceSkill(options);
+        return requestOxygen("/api/cli/skills/workspace/create", {
+            method: "POST",
+            body: {
+                name: options.name,
+                description: options.description,
+                instructions: options.instructions,
+            },
+        });
+    }));
+    workspace
+        .command("import")
+        .description("Upload SKILL.md or a skill folder from any source into private Knowledge. 0 credits.")
+        .option("--file <path>", "Local SKILL.md file.")
+        .option("--directory <path>", "Local skill directory including SKILL.md and supporting text files.")
+        .option("--url <url>", "Import a public HTTPS SKILL.md URL. Supporting files require --directory or --files-json.")
+        .option("--files-json <json>", "Inline array of {path, content}; alternative to --file or --directory.")
+        .option("--name <name>", "Destination name; otherwise use SKILL.md frontmatter name.")
+        .option("--source-url <url>", "HTTPS source provenance; content must already be downloaded.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options, command) => handle("skills workspace import", { json: command.optsWithGlobals().json === true }, async () => {
+        if ([
+            options.file,
+            options.directory,
+            options.url,
+            options.filesJson,
+        ].filter((value) => value !== undefined).length !== 1)
+            throw new OxygenError("invalid_workspace_skill", "Choose exactly one of --file, --directory, --url or --files-json.", { exitCode: 2 });
+        if (options.url !== undefined) {
+            if (options.sourceUrl !== undefined)
+                throw new OxygenError("invalid_workspace_skill", "--source-url is for uploaded files. A URL import records its own source.", { exitCode: 2 });
+            return requestOxygen("/api/cli/skills/workspace/import", {
+                method: "POST",
+                body: {
+                    url: options.url,
+                    ...(options.name ? { name: options.name } : {}),
+                },
+            });
+        }
+        let files;
+        if (options.directory)
+            files = await readWorkspaceSkillDirectory(options.directory);
+        else if (options.file) {
+            const stat = await lstat(options.file);
+            if (!stat.isFile() || stat.size > WORKSPACE_SKILL_MAX_FILE_BYTES)
+                throw new OxygenError("invalid_workspace_skill", "Provide a regular SKILL.md text file of at most 120 KB.", { exitCode: 2 });
+            files = [
+                {
+                    path: "SKILL.md",
+                    content: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(await readFile(options.file)),
+                },
+            ];
+        }
+        else {
+            try {
+                files = JSON.parse(options.filesJson);
+            }
+            catch {
+                throw new OxygenError("invalid_workspace_skill", "--files-json must be a JSON array of {path, content}.", { exitCode: 2 });
+            }
+        }
+        const bundle = parseWorkspaceSkillBundle({
+            files,
+            ...(options.name ? { name: options.name } : {}),
+            ...(options.sourceUrl ? { source_url: options.sourceUrl } : {}),
+        });
+        return requestOxygen("/api/cli/skills/workspace/import", {
+            method: "POST",
+            body: {
+                name: bundle.name,
+                files: bundle.files,
+                ...(bundle.source_url ? { source_url: bundle.source_url } : {}),
+            },
+        });
+    }));
+}

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

@@ -1877,7 +1877,12 @@ function isSubscriptionRetentionIntent(query) {
     return /\b(retention offer|win[ -]?back discount|cancellation (?:reason|feedback)|written cancellation)\b/.test(query)
         || /\b(stay|cancel|cancelling)\b/.test(query) && /\b(discount|next month|subscription reason)\b/.test(query);
 }
+function isWorkspaceSkillIntent(query) {
+    return /\bskills?\b/.test(query) && /\b(create|author|write|upload|import|edit|update|archive|private|workspace|custom|own|reusable)\b/.test(query);
+}
 function explicitCapabilityIntent(query) {
+    if (isWorkspaceSkillIntent(query))
+        return ROUTE_BY_ID.get("knowledge-graph") ?? 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;
@@ -2207,6 +2212,10 @@ 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 === "knowledge-graph" && isWorkspaceSkillIntent(query)) {
+        return { tools: ["oxygen_workspace_skills_list", "oxygen_workspace_skills_create", "oxygen_workspace_skills_import", "oxygen_workspace_skills_get", "oxygen_workspace_skills_update", "oxygen_workspace_skills_archive"],
+            commands: ["skills workspace list", "skills workspace create", "skills workspace import", "skills workspace get", "skills workspace update", "skills workspace archive"] };
+    }
     const contactFind = card.id === "sourcing-and-provider-tools" ? oneShotContactFindingRecommendation(query) : null;
     if (contactFind)
         return contactFind;

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

@@ -13,6 +13,7 @@ import { TABLE_FEED_UPDATE_OPERATION } from "./table-feed-update.js";
 import { GEO_OPERATIONS } from "./geo.js";
 import { CUSTOMER_OPERATIONS } from "./customer-operations.js";
 import { AGENT_SESSION_OPERATIONS } from "./agent-sessions.js";
+import { WORKSPACE_SKILL_OPERATIONS } from "./workspace-skills.js";
 /** The route with its `{param}` segments filled in, each URL-encoded. */
 export function operationPath(spec, params) {
     return spec.route.replace(/\{(\w+)\}/g, (_match, name) => {
@@ -82,6 +83,6 @@ export function operationFormData(spec, body) {
     }
     return form;
 }
-export const OPERATION_SPECS = [SENDER_LIMITS_SET_OPERATION, CONNECTOR_UPDATE_OPERATION, CONNECTOR_EVENTS_REVOKE_OPERATION, WORKSPACE_PAGES_GET_OPERATION, WORKSPACE_PAGES_UPDATE_OPERATION, TABLE_FEED_UPDATE_OPERATION, ...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS];
-export const CLI_OPERATIONS = [...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS].filter((spec) => spec.generated?.cli !== false);
-export const MCP_OPERATIONS = [...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS].filter((spec) => spec.generated?.mcp !== false);
+export const OPERATION_SPECS = [SENDER_LIMITS_SET_OPERATION, CONNECTOR_UPDATE_OPERATION, CONNECTOR_EVENTS_REVOKE_OPERATION, WORKSPACE_PAGES_GET_OPERATION, WORKSPACE_PAGES_UPDATE_OPERATION, TABLE_FEED_UPDATE_OPERATION, ...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS, ...WORKSPACE_SKILL_OPERATIONS];
+export const CLI_OPERATIONS = [...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS, ...WORKSPACE_SKILL_OPERATIONS].filter((spec) => spec.generated?.cli !== false);
+export const MCP_OPERATIONS = [...CUSTOMER_OPERATIONS, ...GEO_OPERATIONS, ...BROWSER_OPERATIONS, ...AGENT_SESSION_OPERATIONS, ...WORKSPACE_SKILL_OPERATIONS].filter((spec) => spec.generated?.mcp !== false);

package/node_modules/@oxygen/shared/dist/contracts/table-query-grid.d.ts

@@ -17,7 +17,7 @@ export declare const TABLE_QUERY_GRID_CONTRACT: import("./schema.js").ContractOb
 }, never>;
 export declare const TABLE_QUERY_GRID_NATIVE_WINDOW = 10000;
 export declare const TABLE_QUERY_GRID_BUILTIN_WINDOW = 4000;
-export declare const TABLE_QUERY_GRID_COPILOT_WINDOW = 24000;
+export declare const TABLE_QUERY_GRID_COPILOT_WINDOW = 50000;
 /** The window a built-in host reads tables in; other clients have none. */
 export declare function tableQueryBuiltinWindow(surface: string | null | undefined): number | undefined;
 /** Measure the complete native receipt and the escaped built-in host receipt. */

package/node_modules/@oxygen/shared/dist/contracts/table-query-grid.js

@@ -12,10 +12,13 @@ export const TABLE_QUERY_GRID_NATIVE_WINDOW = 10_000;
 // Deliberately below Strands' shipped 6000 default; counts the complete host
 // object rather than only its text. This changes no adapter's outer ceiling.
 export const TABLE_QUERY_GRID_BUILTIN_WINDOW = 4_000;
-// The Copilot hands its model the structured result alone, whole up to 32,000
-// characters (ADR 0013, amendment 2026-10-10). One qualified row measured 4,537
-// on dev, so the Agent window refused even a single row (eval, 2026-10-11).
-export const TABLE_QUERY_GRID_COPILOT_WINDOW = 24_000;
+// The Copilot hands its model the structured result alone, and stores one over
+// 12,000 characters for its session so the model reads only the part it needs
+// (ADR 0013, amendments 2026-10-10 and 2026-10-11). Its window is therefore the
+// largest page the MCP layer returns untrimmed (MAX_STRUCTURED_CONTENT_CHARS in
+// @oxygen/mcp-server), not what fits in a conversation. One qualified row
+// measured 4,537 on dev, so the Agent window refuses even a single row.
+export const TABLE_QUERY_GRID_COPILOT_WINDOW = 50_000;
 /** The window a built-in host reads tables in; other clients have none. */
 export function tableQueryBuiltinWindow(surface) {
     if (surface === "copilot")

package/node_modules/@oxygen/shared/dist/contracts/table-query-raw.d.ts

@@ -0,0 +1,14 @@
+/** Opt-in at the API boundary; the CLI supplies these defaults. */
+export declare const TABLE_QUERY_RAW_CONTRACT: import("./schema.js").ContractObject<{
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+}, never>;
+export declare const TABLE_QUERY_CLI_DEFAULT_LIMIT = 20;
+export declare const TABLE_QUERY_CLI_DEFAULT_MAX_CHARS = 12000;
+export declare function tableQueryRawResultFits(data: Record<string, unknown>, maxChars: number | undefined): boolean;
+export declare function tableQueryRawRecovery(table: string, row?: string): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/contracts/table-query-raw.js

@@ -0,0 +1,18 @@
+import { success } from "../cli-result.js";
+import { int, obj } from "./schema.js";
+/** Opt-in at the API boundary; the CLI supplies these defaults. */
+export const TABLE_QUERY_RAW_CONTRACT = obj({
+    max_chars: int({ minimum: 1_000, maximum: 100_000, description: "Result envelope chars." }),
+});
+export const TABLE_QUERY_CLI_DEFAULT_LIMIT = 20;
+export const TABLE_QUERY_CLI_DEFAULT_MAX_CHARS = 12_000;
+export function tableQueryRawResultFits(data, maxChars) {
+    return maxChars === undefined || JSON.stringify(success("tables query", data)).length <= maxChars;
+}
+export function tableQueryRawRecovery(table, row) {
+    return {
+        table,
+        ...(row ? { row } : {}),
+        next_step: "Reduce fields/limit. Inspect a large cell with `tables rows inspect --table <table> --row <row> --field <field> --projection value --path /row/<field>/<key>`; select a JSON Pointer and continue with value_cursor. MCP: hydrate oxygen_table_row_inspect with oxygen_capabilities_schema, then dispatch it through oxygen_capabilities_read. CLI: --full restores legacy reads; --output <path> keeps full JSON outside context.",
+    };
+}

package/node_modules/@oxygen/shared/dist/contracts/workspace-skills.d.ts

@@ -0,0 +1,6 @@
+import type { OperationSpec } from "./operations.js";
+export declare const WORKSPACE_SKILL_FILE_CONTRACT: import("./schema.js").ContractObject<{
+    readonly path: import("./schema.js").StringProperty;
+    readonly content: import("./schema.js").StringProperty;
+}, "content" | "path">;
+export declare const WORKSPACE_SKILL_OPERATIONS: readonly OperationSpec[];