@oxygen-agent/cli 1.948.1 → 1.982.3

package/dist/knowledge-repository-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+export declare function registerKnowledgeRepositoryCommands(program: Command, handle: Handle): void;
+export {};

package/dist/knowledge-repository-commands.js

@@ -0,0 +1,198 @@
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { requestOxygen } from "./http-client.js";
+const post = (path, body) => {
+    if (Buffer.byteLength(JSON.stringify(body)) > 2_000_000)
+        throw new Error("This inline request exceeds 2 MB. Add larger attachments through the connected GitHub repository.");
+    return requestOxygen(`/api/cli/knowledge/${path}`, { method: "POST", body });
+};
+export function registerKnowledgeRepositoryCommands(program, handle) {
+    const knowledge = program.commands.find((c) => c.name() === "knowledge");
+    if (!knowledge)
+        throw new Error("Knowledge commands must be registered first.");
+    const repos = knowledge
+        .command("repositories")
+        .description("Import an existing GitHub or Obsidian repository into Knowledge, or keep it automatically in sync. Start with integrations connect github; web setup: /knowledge/repositories; docs: /docs/knowledge/knowledge-graph.");
+    repos
+        .command("list")
+        .description("Read connected repositories, import progress, sync freshness, pending changes, and errors. 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories list", o, () => post("repositories/list", {})));
+    for (const operation of ["preview", "connect"]) {
+        const cmd = repos
+            .command(operation)
+            .description(operation === "preview"
+            ? "Preview branch/folder contents, exclusions and the future sync policy. Does not activate sync. 0 credits."
+            : "Approve the exact preview and start importing. two_way authorizes future automatic GitHub writes to the selected branch. 0 Oxygen credits.")
+            .requiredOption("--connection-id <id>", "GitHub connection ID from integrations list.")
+            .requiredOption("--repository-id <id>", "Repository ID from integrations github repositories.")
+            .requiredOption("--branch <name>", "Connected branch; unmerged feature branches are separate.")
+            .option("--root-path <path>", "Repository subfolder; omit for the entire repository.", "")
+            .option("--mode <mode>", "two_way or import (one-time copy).", "two_way")
+            .option("--json", "Print a JSON envelope.");
+        if (operation === "connect")
+            cmd
+                .requiredOption("--preview-token <token>", "Exact token returned by repositories preview.")
+                .option("--approved", "Approve the displayed import and future sync policy.");
+        cmd.action((o) => handle(`knowledge repositories ${operation}`, o, () => post(`repositories/${operation}`, {
+            connectionId: o.connectionId,
+            repositoryId: Number(o.repositoryId),
+            branch: o.branch,
+            rootPath: o.rootPath,
+            mode: o.mode,
+            ...(operation === "connect"
+                ? { previewToken: o.previewToken, approved: o.approved === true }
+                : {}),
+        })));
+    }
+    for (const action of ["sync", "pause", "resume", "disconnect"]) {
+        const description = {
+            sync: "Request an immediate sync attempt. Saved changes remain safe if GitHub is unavailable.",
+            pause: "Pause automatic sync; keep all imported files and history.",
+            resume: "Resume the previously approved sync policy.",
+            disconnect: "Disconnect this repository; keep its files and history in Knowledge.",
+        }[action];
+        repos
+            .command(action)
+            .description(description)
+            .requiredOption("--id <id>", "Connected repository mount ID.")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle(`knowledge repositories ${action}`, o, () => post("repositories/action", { id: o.id, action })));
+    }
+    repos
+        .command("conflicts")
+        .description("Read conflicts; add --path to inspect preserved base, Oxygen, and GitHub versions.")
+        .requiredOption("--mount-id <id>", "Connected repository mount ID.")
+        .option("--path <path>", "Exact file path.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories conflicts", o, () => post("repositories/conflicts", {
+        mountId: o.mountId,
+        ...(o.path ? { path: o.path } : {}),
+    })));
+    repos
+        .command("resolve")
+        .description("Apply a reviewed conflict decision. Canonical copy remains proposal-gated; GitHub publishes under the saved sync policy.")
+        .requiredOption("--mount-id <id>", "Connected repository mount ID.")
+        .requiredOption("--path <path>", "Exact file path.")
+        .requiredOption("--local-revision <revision|null>", "Reviewed Oxygen revision or null.")
+        .requiredOption("--remote-sha <sha|null>", "Reviewed GitHub blob SHA or null.")
+        .requiredOption("--decision <choice>", "oxygen, github, or merged.")
+        .option("--file <path>", "Complete edited UTF-8 file for merged.")
+        .option("--approved", "Approve this exact decision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge repositories resolve", o, async () => post("repositories/resolve", {
+        mountId: o.mountId,
+        path: o.path,
+        expectedLocalRevision: o.localRevision === "null" ? null : Number(o.localRevision),
+        expectedRemoteSha: o.remoteSha === "null" ? null : o.remoteSha,
+        decision: o.decision,
+        ...(o.file ? { text: await readFile(String(o.file), "utf8") } : {}),
+        approved: o.approved === true,
+    })));
+    const files = knowledge
+        .command("files")
+        .description("Original repository paths and immutable file revisions, including attachments.");
+    files
+        .command("list")
+        .requiredOption("--mount-id <id>", "Connected repository ID.")
+        .option("--cursor <cursor>", "Continue the previous page.")
+        .option("--limit <number>", "Maximum files, up to 500.", "100")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files list", o, () => post("files/list", {
+        mountId: o.mountId,
+        limit: Number(o.limit),
+        ...(o.cursor ? { cursor: o.cursor } : {}),
+    })));
+    files
+        .command("get")
+        .description("Read original file content, properties and download link at an optional immutable revision.")
+        .requiredOption("--id <id>", "File ID from files list.")
+        .option("--revision <number>", "Specific saved file revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files get", o, () => post("files/get", {
+        id: o.id,
+        ...(o.revision ? { revision: Number(o.revision) } : {}),
+    })));
+    files
+        .command("upsert")
+        .description("Create or replace an original file, or update frontmatter properties. Canonical copy still requires a proposal.")
+        .requiredOption("--mount-id <id>", "Connected repository ID.")
+        .option("--id <id>", "Existing file ID.")
+        .option("--path <path>", "Exact repository-relative path; required for new files.")
+        .requiredOption("--expected-revision <number>", "Reviewed file revision; 0 creates a new file.")
+        .option("--file <path>", "Complete local file, including any frontmatter or binary bytes.")
+        .option("--properties-json <json>", "Frontmatter properties to change; mutually exclusive with --file.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files upsert", o, async () => {
+        if (Boolean(o.file) === Boolean(o.propertiesJson))
+            throw new Error("Provide exactly one of --file or --properties-json.");
+        if (o.file && (await stat(String(o.file))).size > 1_500_000)
+            throw new Error("Inline file uploads must fit a 2 MB JSON request (including base64). Add larger attachments through the connected GitHub repository.");
+        const patch = o.propertiesJson
+            ? JSON.parse(String(o.propertiesJson))
+            : undefined;
+        if (patch !== undefined &&
+            (!patch || typeof patch !== "object" || Array.isArray(patch)))
+            throw new Error("--properties-json must contain an object.");
+        return post("files/upsert", {
+            mountId: o.mountId,
+            ...(o.id ? { id: o.id } : {}),
+            ...(o.path ? { path: o.path } : {}),
+            expectedFileRevision: Number(o.expectedRevision),
+            ...(o.file
+                ? {
+                    bytesBase64: (await readFile(String(o.file))).toString("base64"),
+                }
+                : { propertyPatch: patch }),
+        });
+    }));
+    files
+        .command("archive")
+        .description("Archive a file with revision checking. A connected two-way repository publishes the deletion; history remains.")
+        .requiredOption("--id <id>", "File ID.")
+        .requiredOption("--expected-revision <number>", "Reviewed file revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files archive", o, () => post("files/archive", {
+        id: o.id,
+        expectedFileRevision: Number(o.expectedRevision),
+    })));
+    files
+        .command("download")
+        .description("Download exact original bytes with digest verification; refuses to overwrite an existing local file.")
+        .requiredOption("--id <id>", "File ID.")
+        .requiredOption("--out <path>", "New local destination filename.")
+        .option("--revision <number>", "Specific immutable revision.")
+        .option("--json", "Print a JSON envelope.")
+        .action((o) => handle("knowledge files download", o, async () => {
+        const query = new URLSearchParams({
+            id: String(o.id),
+            ...(o.revision ? { revision: String(o.revision) } : {}),
+        });
+        const data = await requestOxygen(`/api/cli/knowledge/files/get?${query}`);
+        const bytes = await requestOxygen(`/api/cli/knowledge/files/download?${query}`, { binaryMaxBytes: Math.max(1, data.file.sizeBytes) });
+        if (bytes.length !== data.file.sizeBytes ||
+            createHash("sha256").update(bytes).digest("hex") !== data.file.sha256)
+            throw new Error("Downloaded bytes do not match the saved file revision.");
+        await writeFile(String(o.out), bytes, { flag: "wx", mode: 0o600 });
+        return { path: resolve(String(o.out)), ...data.file };
+    }));
+    const integrations = program.commands.find((c) => c.name() === "integrations");
+    if (integrations) {
+        const github = integrations
+            .command("github")
+            .description("Choose repositories authorized through the GitHub App. Connect first with integrations connect github. The Oxygen GitHub App requests Contents read and write plus Metadata read on the repositories you select, and push events; it requests no account or organization permissions. integrations list reports GitHub availability for this deployment.");
+        github
+            .command("repositories")
+            .requiredOption("--connection-id <id>", "GitHub connection ID.")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle("integrations github repositories", o, () => requestOxygen(`/api/cli/integrations/github/repositories?connection_id=${encodeURIComponent(String(o.connectionId))}`)));
+        github
+            .command("branches")
+            .requiredOption("--connection-id <id>", "GitHub connection ID.")
+            .requiredOption("--repository-id <id>", "Immutable GitHub repository ID.")
+            .option("--page <number>", "Page to read.", "1")
+            .option("--json", "Print a JSON envelope.")
+            .action((o) => handle("integrations github branches", o, () => requestOxygen(`/api/cli/integrations/github/branches?${new URLSearchParams({ connection_id: String(o.connectionId), repository_id: String(o.repositoryId), page: String(o.page) })}`)));
+    }
+}

package/dist/skills.js

@@ -66,6 +66,17 @@ export async function resolveSkillsInstallSource(options) {
         return publicSource(`access_unavailable:${code}`);
     }
 }
+function requireSkillContentAccess(index, source) {
+    if (!index.authentication_required)
+        return;
+    throw new OxygenError("skills_authentication_required", "Sign in to download Oxygen agent instructions.", {
+        details: {
+            next_step: "Run `oxygen login`, then retry `oxygen skills install` or `oxygen skills get`.",
+            ...(source.fallback_reason ? { access_fallback: source.fallback_reason } : {}),
+        },
+        exitCode: 1,
+    });
+}
 export async function listAgentSkills(options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
     const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
@@ -137,6 +148,7 @@ export async function getAgentSkill(skillName, options, runtime = {}) {
             exitCode: 1,
         });
     }
+    requireSkillContentAccess(index, source);
     const normalized = skillName.trim();
     const skill = index.skills.find((entry) => entry.name === normalized);
     if (!skill) {
@@ -203,6 +215,12 @@ options, runtime = {}) {
         ...(runtime.credentials !== undefined ? { credentials: runtime.credentials } : {}),
         ...(runtime.fetch ? { fetch: runtime.fetch } : {}),
     });
+    if (!source.authenticated) {
+        // Public discovery remains usable. New servers explicitly mark that their
+        // instruction bodies require a signed workspace link; never invoke the
+        // installer against that discovery-only catalog.
+        requireSkillContentAccess(await inspectSkillIndex(source.index_url, runtime.fetch), source);
+    }
     const agents = readWords(options.agents ?? DEFAULT_SKILL_AGENTS);
     const skill = readOption(options.skill) ?? "*";
     const env = runtime.env ?? process.env;
@@ -599,6 +617,7 @@ async function inspectSkillIndex(indexUrl, fetchImpl = fetch) {
         }
         return {
             reachable: true,
+            authentication_required: index.authentication_required === true,
             status: response.status,
             version: index.version,
             base_url: index.base_url,
@@ -667,6 +686,7 @@ function parseSkillIndex(value) {
     })
         .filter((entry) => entry !== null);
     return {
+        authentication_required: value.authentication_required === true,
         version: typeof value.version === "string" ? value.version : null,
         base_url: typeof value.base_url === "string" ? value.base_url : null,
         skills,

package/dist/ugc-commands.js

@@ -27,10 +27,11 @@ function parseField(value, field) {
 export function registerUgcCommands(program, handle) {
     const ugc = program
         .command("ugc")
-        .description("Manage UGC programs and independent creator participations: briefs, voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability.");
+        .description("Manage UGC programs and independent creator participations: briefs, voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability. Start with memberships list in a creator workspace. See the oxygen-ugc skill; JSON reads return web_url for inspection.");
     const groupDescriptions = {
         programs: "Programs you operate or joined. Lifecycle: create, update, duplicate (settings + briefs), archive (stops future work, keeps shared history, reversible with restore) and delete (permanent; only while no creator has ever joined).",
         creators: "Creator participations: invite, revoke an invite, accept in the creator workspace, connect a sender, change approval authority, or revoke.",
+        memberships: "Active programs this creator workspace has joined. Read these before choosing a program for a personal post.",
         briefs: "Program briefs with ordered questions for creators.",
         posts: "Enrolled program posts: enroll existing posts, draft from briefs, edit, schedule, and record creator or brand approval.",
         analytics: "Stored daily program and creator performance.",
@@ -38,6 +39,7 @@ export function registerUgcCommands(program, handle) {
         voice: "Creator voice profiles and imports.",
         sponsorship: "Seat and credit sponsorship per participation.",
         amplification: "Bounded, approval-gated amplification of enrolled posts.",
+        "peer-amplification": "Creator-owned consent, sender, voice, caps and immutable receipts for engaging with peer posts in one program.",
         calendar: "Bounded enrolled-post calendar reads.",
     };
     const groups = new Map();
@@ -97,6 +99,11 @@ export function registerUgcCommands(program, handle) {
             query.set("participation_id", String(options.participationId));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
+    group("memberships")
+        .command("list")
+        .description("Read active program memberships for the creator workspace. Free, stored and provider-free.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc memberships list", options, () => requestOxygen("/api/cli/ugc?view=memberships")));
     group("briefs")
         .command("list")
         .description("Read one program's UGC briefs. Read-only; requires --program-id.")
@@ -117,6 +124,8 @@ export function registerUgcCommands(program, handle) {
         .description("Read UGC posts in the active workspace. Read-only.")
         .requiredOption("--program-id <id>", "Program ID.")
         .option("--participation-id <id>", "Creator participation ID.")
+        .option("--post-id <id>", "Read one canonical post ID.")
+        .option("--enrollment-version <n>", "Read one exact enrollment version after a post was removed and re-added.")
         .option("--cursor <cursor>", "Opaque next_cursor from the previous page.")
         .option("--limit <count>", "Posts per page, 1–500.")
         .option("--json", "Print a JSON envelope.")
@@ -126,6 +135,10 @@ export function registerUgcCommands(program, handle) {
             query.set("program_id", String(options.programId));
         if (options.participationId)
             query.set("participation_id", String(options.participationId));
+        if (options.postId)
+            query.set("post_id", String(options.postId));
+        if (options.enrollmentVersion)
+            query.set("enrollment_version", String(options.enrollmentVersion));
         if (options.cursor)
             query.set("cursor", String(options.cursor));
         if (options.limit)
@@ -232,6 +245,12 @@ export function registerUgcCommands(program, handle) {
             description: "Read retained public comments, metrics, and publication receipts for one enrolled post. Stored data only, 0 credits.",
             fields: [
                 ["post_id", "Enrolled source post UUID.", true],
+                [
+                    "enrollment_version",
+                    "Exact enrollment_version returned by posts list; required to distinguish remove/re-enroll history.",
+                    true,
+                ],
+                ["participation_id", "Exact creator participation ID.", false],
                 ["cursor", "next_comments_cursor from the previous page.", false],
                 ["metric_cursor", "next_metrics_cursor from the previous page.", false],
                 ["action_cursor", "next_actions_cursor from the previous page.", false],
@@ -244,20 +263,30 @@ export function registerUgcCommands(program, handle) {
             description: "Read this program's current amplification authority and immutable action history. Master workspace only; 0 credits, no provider call.",
             fields: [["cursor", "next_cursor from the previous action page.", false]],
         },
+        {
+            group: "peer-amplification",
+            command: "get",
+            view: "peer_amplification",
+            description: "Read this creator's own peer-engagement policy, host gate, readiness and immutable receipts. Creator workspace only; free and provider-free.",
+            fields: [
+                ["participation_id", "Exact creator participation ID.", true],
+                ["cursor", "next_cursor from the previous action page.", false],
+            ],
+            programRequired: false,
+        },
     ]) {
         const command = group(spec.group)
             .command(spec.command)
             .description(spec.description)
-            .requiredOption("--program-id <id>", "Program ID.")
             .option("--limit <count>", "Rows per page, up to 100.")
             .option("--json", "Print a JSON envelope.");
+        command["programRequired" in spec && spec.programRequired === false ? "option" : "requiredOption"]("--program-id <id>", "Program ID.");
         for (const [name, description, required] of spec.fields)
             command[required ? "requiredOption" : "option"](`--${name.replaceAll("_", "-")} <value>`, description);
         command.action((options) => handle(`ugc ${spec.group} ${spec.command}`, options, () => {
-            const query = new URLSearchParams({
-                view: spec.view,
-                program_id: String(options.programId),
-            });
+            const query = new URLSearchParams({ view: spec.view });
+            if (options.programId)
+                query.set("program_id", String(options.programId));
             for (const [name] of spec.fields) {
                 const key = name.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
                 if (options[key] !== undefined)
@@ -347,6 +376,12 @@ export function registerUgcCommands(program, handle) {
                     description: "Require a separate brand approval before publishing.",
                     required: false,
                 },
+                {
+                    name: "peer_engagement_enabled",
+                    kind: "boolean",
+                    description: "Host permission for creators in this program to opt into peer engagement; enabling requires a signed-in master admin.",
+                    required: false,
+                },
                 {
                     name: "status",
                     kind: "string",
@@ -536,7 +571,7 @@ export function registerUgcCommands(program, handle) {
         {
             action: "participation_update",
             command: "creators update",
-            description: "Connect an existing LinkedIn sender, change approval authority, or revoke participation.",
+            description: "Connect an existing LinkedIn sender, change approval authority, or leave the entire program. Revocation stops future sharing and program actions; your posts stay in your workspace and the organizer retains previously shared history. This workspace cannot currently rejoin the same program. To remove one post while staying, use ugc posts remove.",
             fields: [
                 {
                     name: "participation_id",
@@ -559,7 +594,7 @@ export function registerUgcCommands(program, handle) {
                 {
                     name: "status",
                     kind: "string",
-                    description: "Program status, or revoked for a participation.",
+                    description: "Use revoked to leave the entire program. This participation cannot be restored.",
                     required: false,
                 },
             ],
@@ -663,6 +698,37 @@ export function registerUgcCommands(program, handle) {
                 },
             ],
         },
+        {
+            action: "post_remove",
+            command: "posts remove",
+            description: "Remove one creator-owned post from a program before publication while retaining immutable enrollment history. The personal draft remains in Publishing.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical personal post ID.",
+                    required: true,
+                },
+                {
+                    name: "enrollment_id",
+                    kind: "string",
+                    description: "Exact active enrollment ID returned by posts list.",
+                    required: true,
+                },
+                {
+                    name: "source_revision",
+                    kind: "string",
+                    description: "Exact current content fingerprint returned by posts list.",
+                    required: true,
+                },
+            ],
+        },
         {
             action: "draft_create",
             command: "posts draft",
@@ -723,6 +789,12 @@ export function registerUgcCommands(program, handle) {
                     description: "Canonical post ID.",
                     required: true,
                 },
+                {
+                    name: "enrollment_version",
+                    kind: "number",
+                    description: "Exact enrollment version returned by posts list; always send it so a removed/re-enrolled post cannot reuse an old edit.",
+                    required: true,
+                },
                 {
                     name: "title",
                     kind: "string",
@@ -760,6 +832,12 @@ export function registerUgcCommands(program, handle) {
                     description: "Canonical post ID.",
                     required: true,
                 },
+                {
+                    name: "enrollment_version",
+                    kind: "number",
+                    description: "Exact enrollment version returned by posts list; always send it so approval binds the current enrollment.",
+                    required: true,
+                },
                 {
                     name: "source_revision",
                     kind: "string",
@@ -791,6 +869,12 @@ export function registerUgcCommands(program, handle) {
                     description: "Canonical post ID.",
                     required: true,
                 },
+                {
+                    name: "enrollment_version",
+                    kind: "number",
+                    description: "Exact enrollment version returned by posts list; always send it so brand approval binds the current enrollment.",
+                    required: true,
+                },
                 {
                     name: "source_revision",
                     kind: "string",
@@ -1046,6 +1130,36 @@ export function registerUgcCommands(program, handle) {
                 },
             ],
         },
+        {
+            action: "peer_amplification_save",
+            command: "peer-amplification save",
+            description: "Preview or save this creator workspace's own peer-engagement consent, sender, voice and caps. The creator wallet pays; the host gate must also be enabled.",
+            fields: [
+                { name: "participation_id", kind: "string", description: "Exact creator participation ID.", required: true },
+                { name: "sender_account_id", kind: "string", description: "Creator's matching connected LinkedIn sender ID.", required: true },
+                { name: "voice_page_id", kind: "string", description: "Creator-owned active voice page ID, required for comment or repost.", required: false },
+                { name: "actions", kind: "array", description: "Allowed peer actions: reaction, comment or repost.", required: true },
+                { name: "enabled", kind: "boolean", description: "Enable or disable this creator-owned policy.", required: true },
+                { name: "expected_policy_version", kind: "number", description: "Current policy version from peer-amplification get; omit or use 0 on first save.", required: false },
+                { name: "max_actions_per_post", kind: "number", description: "Hard action cap per peer post.", required: true },
+                { name: "max_credits_per_cycle", kind: "number", description: "Hard creator-wallet credit cap per cycle.", required: true },
+                { name: "approved", kind: "boolean", description: "Confirm this exact creator-owned scope; omit for preview.", required: false },
+                { name: "delay_min_seconds", kind: "number", description: "Minimum delay, 60–3600 seconds.", required: false },
+                { name: "delay_max_seconds", kind: "number", description: "Maximum delay, 60–86400 seconds.", required: false },
+            ],
+        },
+        {
+            action: "peer_amplification_reconcile",
+            command: "peer-amplification reconcile",
+            description: "Preview recording observed evidence for this creator's effect_unknown peer action. Approval records the outcome without a provider call or retry.",
+            fields: [
+                { name: "participation_id", kind: "string", description: "Exact creator participation ID.", required: true },
+                { name: "action_id", kind: "string", description: "Exact effect_unknown peer action ID.", required: true },
+                { name: "outcome", kind: "string", description: "Observed applied or not_applied outcome.", required: true },
+                { name: "evidence", kind: "object", description: "JSON evidence: provider_post_id, evidence_ref and observed_at; applied may require provider_object_id and exact observed_text.", required: true },
+                { name: "approved", kind: "boolean", description: "Confirm this immutable observation; no retry is authorized.", required: false },
+            ],
+        },
     ];
     for (const spec of writes) {
         const [family, leaf] = spec.command.split(" ");

package/node_modules/@oxygen/recipe-sdk/dist/index.d.ts

@@ -7,6 +7,8 @@ export type RecipeToolRunOptions = {
     optional?: boolean;
     /** Pin this call to one provider account for every replay/scheduled run. */
     connectionId?: string;
+    /** Pin the credential rail instead of automatically selecting a connected key. */
+    credentialMode?: "managed" | "user_api_key" | "user_oauth";
 };
 export type RecipeToolApi = {
     run: <T = unknown>(toolId: string, payload?: Record<string, unknown>, options?: RecipeToolRunOptions) => Promise<T>;

package/node_modules/@oxygen/shared/dist/capability-discovery.d.ts

@@ -23,6 +23,12 @@ export type CapabilityRouteMatch = {
     card: CapabilityRouteCard;
     recommendedTools: string[];
     recommendedCommands: string[];
+    /**
+     * The one exact invocation for asks whose answer is a single command with a
+     * specific flag the help text alone did not teach. Present only when the
+     * intent is that narrow; `recommendedCommands[0]` is the same command.
+     */
+    exactCommand?: string;
 };
 export type PrimitiveRouteMatch = CapabilityRouteMatch & {
     card: PrimitiveRouteCard;
@@ -34,3 +40,5 @@ export declare function getCapabilityRouteMatch(id: string): CapabilityRouteMatc
 export declare function inferCapabilityRoute(query: string): CapabilityRouteMatch | null;
 export declare function inferPrimitiveRoute(query: string): PrimitiveRouteMatch | null;
 export declare function serializeCapabilityRoute(route: CapabilityRouteMatch | null): Record<string, unknown> | null;
+/** The exact `companies search plan` invocation for the url_recovery intent. */
+export declare const COMPANY_URL_RECOVERY_COMMAND = "oxygen companies search plan --prompt \"Find the websites for these companies: <company names>\" --source-intent url_recovery";