@oxygen-agent/cli 1.1014.18 → 1.1014.69

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

@@ -47,6 +47,10 @@ const WARN_THROTTLE_MS = 30_000;
  * meant every flush that ran long lost its spans instead of finishing late.
  */
 const LANGFUSE_EXPORT_TIMEOUT_SECONDS = 10;
+// Keep retries below BSP's 30s batch deadline. Shutdown must outlive delivery;
+// ordinary flush callers still return at their existing fail-open bound.
+const LANGFUSE_EXPORT_BUDGET_MS = 25_000;
+const LANGFUSE_SHUTDOWN_TIMEOUT_MS = 30_000;
 // Scores are API strings; unlike observation payloads they cannot use chunks.
 const MAX_JSON_FIELD_CHARS = 400_000;
 /**
@@ -183,10 +187,12 @@ function compact(body) {
 // many spans Langfuse acknowledged, how many batches it refused, and how many
 // observations never reached the exporter at all. Counts only; never content.
 const EXPORT_SUMMARY_INTERVAL_MS = 60_000;
-export function createLlmExportSummary(now = Date.now) {
+export function createLlmExportSummary(now = Date.now, context = {}) {
     let exported = 0;
     let failed = 0;
     let dropped = 0;
+    let retried = 0;
+    let recovered = 0;
     let windowStartedAt = now();
     const report = () => {
         const at = now();
@@ -196,12 +202,17 @@ export function createLlmExportSummary(now = Date.now) {
                 exported,
                 failed,
                 dropped,
+                retried,
+                recovered,
+                ...context,
                 window_seconds: Math.max(0, Math.round((at - windowStartedAt) / 1000)),
             });
         }
         exported = 0;
         failed = 0;
         dropped = 0;
+        retried = 0;
+        recovered = 0;
         windowStartedAt = at;
     };
     const add = (count) => (Number.isFinite(count) && count > 0 ? Math.floor(count) : 0);
@@ -209,6 +220,8 @@ export function createLlmExportSummary(now = Date.now) {
         exported: (count) => { exported += add(count); },
         failed: (count) => { failed += add(count); },
         dropped: (count) => { dropped += add(count); },
+        retried: () => { retried++; },
+        recovered: (count) => { recovered += add(count); },
         maybeReport: () => { if (now() - windowStartedAt >= EXPORT_SUMMARY_INTERVAL_MS)
             report(); },
         reportNow: report,
@@ -270,75 +283,95 @@ function createOtelEmitter(env, warn, summary) {
                     if (!encoded)
                         throw new Error("serialization_failed");
                     const body = new TextDecoder().decode(encoded);
-                    const signal = AbortSignal.timeout(LANGFUSE_EXPORT_TIMEOUT_SECONDS * 1000);
-                    let response;
+                    const startedAt = Date.now();
+                    let status;
+                    let failureKind = "transport_failed";
+                    let attempts = 0;
                     for (let attempt = 0; attempt < 3; attempt++) {
-                        try {
-                            response = await fetch(exportUrl, { method: "POST", headers: exportHeaders, body, signal, redirect: "error" });
-                        }
-                        catch {
-                            if (signal.aborted)
-                                throw new Error("deadline_exceeded");
-                            if (attempt === 2)
-                                throw new Error("network_failed");
-                            await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
-                            continue;
-                        }
-                        if (![429, 502, 503, 504].includes(response.status) || attempt === 2)
+                        const remaining = LANGFUSE_EXPORT_BUDGET_MS - (Date.now() - startedAt);
+                        if (remaining <= 0)
                             break;
-                        // A retryable rejection has no useful private response to retain.
-                        await response.body?.cancel().catch(() => { });
-                        await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
-                    }
-                    if (!response?.ok) {
-                        await response?.body?.cancel().catch(() => { });
-                        throw new Error("http_rejected");
-                    }
-                    const chunks = [];
-                    let bytes = 0;
-                    const reader = response.body?.getReader();
-                    if (reader) {
+                        attempts = attempt + 1;
+                        status = undefined;
+                        const signal = AbortSignal.timeout(Math.min(LANGFUSE_EXPORT_TIMEOUT_SECONDS * 1000, remaining));
+                        let response;
                         try {
-                            for (;;) {
-                                const next = await reader.read();
-                                if (next.done)
-                                    break;
-                                bytes += next.value.byteLength;
-                                // OTLP acknowledgements are tiny; an echoed payload must never
-                                // become an unbounded allocation or reach any diagnostic logger.
-                                if (bytes > 64 * 1024)
-                                    throw new Error("response_too_large");
-                                chunks.push(next.value);
+                            try {
+                                response = await fetch(exportUrl, { method: "POST", headers: exportHeaders, body, signal, redirect: "error" });
+                            }
+                            catch {
+                                throw new Error(signal.aborted ? "deadline_exceeded" : "network_failed");
                             }
+                            status = response.status;
+                            if (!response.ok) {
+                                await response.body?.cancel().catch(() => { });
+                                throw new Error("http_rejected");
+                            }
+                            const chunks = [];
+                            let bytes = 0;
+                            const reader = response.body?.getReader();
+                            if (reader) {
+                                try {
+                                    for (;;) {
+                                        const next = await reader.read();
+                                        if (next.done)
+                                            break;
+                                        bytes += next.value.byteLength;
+                                        // Never allocate or log an unbounded echoed private payload.
+                                        if (bytes > 64 * 1024)
+                                            throw new Error("response_too_large");
+                                        chunks.push(next.value);
+                                    }
+                                }
+                                catch (error) {
+                                    await reader.cancel().catch(() => { });
+                                    throw new Error(signal.aborted ? "deadline_exceeded" : error instanceof Error && error.message === "response_too_large" ? "response_too_large" : "response_read_failed");
+                                }
+                                finally {
+                                    reader.releaseLock();
+                                }
+                            }
+                            let acknowledgement;
+                            try {
+                                acknowledgement = bytes ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : {};
+                            }
+                            catch {
+                                throw new Error("response_invalid");
+                            }
+                            if (!acknowledgement || typeof acknowledgement !== "object" || Array.isArray(acknowledgement))
+                                throw new Error("response_invalid");
+                            const envelope = acknowledgement;
+                            const partial = envelope.partialSuccess ?? envelope.partial_success;
+                            if (partial !== undefined && partial !== null) {
+                                if (typeof partial !== "object" || Array.isArray(partial))
+                                    throw new Error("response_invalid");
+                                const rawRejected = partial.rejectedSpans ?? partial.rejected_spans ?? 0;
+                                if ((typeof rawRejected !== "number" && typeof rawRejected !== "string") || !/^\d+$/.test(String(rawRejected)))
+                                    throw new Error("response_invalid");
+                                if (Number(rawRejected) > 0)
+                                    throw new Error("partial_rejection");
+                            }
+                            if (attempt > 0)
+                                summary.recovered(spans.length);
+                            return;
                         }
                         catch (error) {
-                            await reader.cancel().catch(() => { });
-                            throw new Error(error instanceof Error && error.message === "response_too_large" ? "response_too_large" : "response_read_failed");
-                        }
-                        finally {
-                            reader.releaseLock();
+                            failureKind = error instanceof Error ? error.message : "transport_failed";
+                            const retryable = ["deadline_exceeded", "network_failed", "response_read_failed"].includes(failureKind)
+                                || (failureKind === "http_rejected" && [429, 502, 503, 504].includes(status ?? 0));
+                            if (!retryable || attempt === 2) {
+                                // Carry fixed classifications and numbers only, never an SDK or
+                                // receiver error that could quote the request/response payload.
+                                throw Object.assign(new Error(failureKind), { attempts: attempt + 1, status });
+                            }
+                            const pause = 100 * (attempt + 1);
+                            if (LANGFUSE_EXPORT_BUDGET_MS - (Date.now() - startedAt) <= pause)
+                                break;
+                            summary.retried();
+                            await new Promise((resolve) => setTimeout(resolve, pause));
                         }
                     }
-                    let acknowledgement;
-                    try {
-                        acknowledgement = bytes ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : {};
-                    }
-                    catch {
-                        throw new Error("response_invalid");
-                    }
-                    if (!acknowledgement || typeof acknowledgement !== "object" || Array.isArray(acknowledgement))
-                        throw new Error("response_invalid");
-                    const envelope = acknowledgement;
-                    const partial = envelope.partialSuccess ?? envelope.partial_success;
-                    if (partial !== undefined && partial !== null) {
-                        if (typeof partial !== "object" || Array.isArray(partial))
-                            throw new Error("response_invalid");
-                        const rawRejected = partial.rejectedSpans ?? partial.rejected_spans ?? 0;
-                        if ((typeof rawRejected !== "number" && typeof rawRejected !== "string") || !/^\d+$/.test(String(rawRejected)))
-                            throw new Error("response_invalid");
-                        if (Number(rawRejected) > 0)
-                            throw new Error("partial_rejection");
-                    }
+                    throw Object.assign(new Error(failureKind), { attempts, status });
                 };
                 const privateExporter = {
                     export: (spans, done) => {
@@ -356,7 +389,9 @@ function createOtelEmitter(env, warn, summary) {
                             done({ code: 1, error: new Error("langfuse_delivery_failed") });
                             summary.failed(spans.length);
                             summary.maybeReport();
-                            warn(error, { stage: "export", observation_count: spans.length, failure_kind: failureKind });
+                            const details = error;
+                            warn(error, { stage: "export", observation_count: spans.length, failure_kind: failureKind,
+                                attempts: details.attempts, http_status: details.status });
                         });
                         pendingExports.add(pending);
                         // Even an unexpected SDK callback failure must not create a rejected
@@ -453,7 +488,23 @@ function createOtelEmitter(env, warn, summary) {
                         identity = undefined;
                     }
                 };
-                return { processor, emit };
+                return { processor: {
+                        // BSP forceFlush drains its queue, but does not wait for a batch its
+                        // interval already removed. Always drain our active exporter too,
+                        // including when the queued batch rejects.
+                        forceFlush: async () => { try {
+                            await processor.forceFlush();
+                        }
+                        finally {
+                            await privateExporter.forceFlush();
+                        } },
+                        shutdown: async () => { try {
+                            await processor.shutdown();
+                        }
+                        finally {
+                            await privateExporter.shutdown();
+                        } },
+                    }, emit };
             }
             catch (error) {
                 warn(error, { stage: "init" });
@@ -693,6 +744,11 @@ export function createLlmTracingClient(env = process.env, options) {
         }
         return null;
     }
+    const deliveryContext = {
+        tracing_environment: resolveLlmTracingEnvironment(env),
+        worker_role: ["relay", "bulk", "interactive", "provider", "outbound", "maintenance"].includes(env.OXYGEN_WORKER_QUEUE_ROLE ?? "")
+            ? env.OXYGEN_WORKER_QUEUE_ROLE : undefined,
+    };
     const lastWarnAtMs = new Map();
     const warn = (error, context) => {
         const nowMs = Date.now();
@@ -708,6 +764,7 @@ export function createLlmTracingClient(env = process.env, options) {
             // Exporter/API error messages can contain the rejected request or server
             // response. Only this fixed classification may leave the private store.
             error_code: errorCode,
+            ...deliveryContext,
             ...context,
         });
     };
@@ -738,7 +795,7 @@ export function createLlmTracingClient(env = process.env, options) {
         return observationSpanId(["langfuse-observation-v1", body.traceId, kind, body.name, body.id,
             body.startTime.toISOString(), body.metadata?.attempt_id ?? null, body.metadata?.call_id ?? null]);
     };
-    const summary = createLlmExportSummary();
+    const summary = createLlmExportSummary(Date.now, deliveryContext);
     const transport = options?.emitterImpl ?? createOtelEmitter(env, warn, summary);
     const emitter = {
         ...transport,
@@ -970,7 +1027,7 @@ export function createLlmTracingClient(env = process.env, options) {
         }
         finally {
             summary.reportNow();
-        } })(), (error) => warn(error, { stage: "shutdown" }), env.VERCEL ? 15_000 : FLUSH_TIMEOUT_MS),
+        } })(), (error) => warn(error, { stage: "shutdown" }), LANGFUSE_SHUTDOWN_TIMEOUT_MS),
     };
 }
 // --- Process-wide singleton (both runtimes construct at most one client) ------

package/node_modules/@oxygen/shared/dist/table-run-summary.d.ts

@@ -0,0 +1,2 @@
+/** Project the already-authorized, customer-safe native run; no provider or retry effects. */
+export declare function tableRunSummary(run: Record<string, unknown>): Record<string, unknown>;

package/node_modules/@oxygen/shared/dist/table-run-summary.js

@@ -0,0 +1,26 @@
+const SUMMARY_FIELDS = new Set([
+    "id", "runId", "tableId", "tableSlug", "status", "counts", "countsAvailable", "summaryLevel", "progress_counts_available", "creditsUsed", "creditsReserved",
+    "createdAt", "updatedAt", "startedAt", "completedAt", "lastError", "action_run_id",
+    "workspace_run_id", "table_id", "table_slug", "web_url", "deepLink", "plan",
+    "execution_status", "health_status", "user_status", "user_message", "progress_label",
+    "next_best_action", "recommended_action", "next_actions", "queue_age_seconds",
+    "deferred_count", "retrying_count", "credit_limit_skipped", "throughput", "bottlenecks",
+    "provider_errors", "provider_health", "provider_timeout_breaker", "classification_review",
+    "worker_health", "queue_backend", "execution_backend", "max_concurrency_requested",
+    "max_concurrency_effective", "enrichment_rollup", "idempotent_replay",
+]);
+/** Project the already-authorized, customer-safe native run; no provider or retry effects. */
+export function tableRunSummary(run) {
+    if (run.view === "summary")
+        return run;
+    const included = (key) => SUMMARY_FIELDS.has(key) || /credit|cost|approval|error|failure/i.test(key);
+    const id = run.action_run_id ?? run.id;
+    return {
+        ...Object.fromEntries(Object.entries(run).filter(([key]) => included(key))),
+        view: "summary",
+        omitted_fields: Object.keys(run).filter((key) => !included(key)).sort(),
+        full_read: { tool: "oxygen_table_runs_get", arguments: { action_run_id: id, view: "full" },
+            gateway: { tool: "oxygen_capabilities_read", arguments: { tool: "oxygen_table_runs_get", arguments: { action_run_id: id, view: "full" } } },
+            cli: `oxygen table-runs get ${String(id)} --full --json` },
+    };
+}

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

@@ -1 +1 @@
-export declare const OXYGEN_BUILD_VERSION = "1.1014.18";
+export declare const OXYGEN_BUILD_VERSION = "1.1014.69";

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

@@ -1,2 +1,2 @@
 // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
-export const OXYGEN_BUILD_VERSION = "1.1014.18";
+export const OXYGEN_BUILD_VERSION = "1.1014.69";

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

@@ -0,0 +1,26 @@
+export declare const WORKSPACE_SKILL_MAX_FILES = 50;
+export declare const WORKSPACE_SKILL_MAX_FILE_BYTES = 120000;
+export declare const WORKSPACE_SKILL_MAX_BYTES = 1000000;
+export type WorkspaceSkillFile = {
+    path: string;
+    content: string;
+};
+export type WorkspaceSkillBundle = {
+    name: string;
+    description: string;
+    files: WorkspaceSkillFile[];
+    source_url?: string;
+};
+export declare function workspaceSkillPath(path: unknown): string;
+export declare function validateWorkspaceSkillFile(file: WorkspaceSkillFile): number;
+/** Content stays verbatim. Names and paths are metadata, never tool authority. */
+export declare function parseWorkspaceSkillBundle(input: {
+    files: readonly WorkspaceSkillFile[];
+    name?: string;
+    source_url?: string;
+}): WorkspaceSkillBundle;
+export declare function authorWorkspaceSkill(input: {
+    name: string;
+    description: string;
+    instructions: string;
+}): WorkspaceSkillBundle;

package/node_modules/@oxygen/shared/dist/workspace-skills.js

@@ -0,0 +1,102 @@
+import { OxygenError } from "./cli-result.js";
+import { parseKnowledgeVaultMarkdown } from "./knowledge-vault-markdown.js";
+export const WORKSPACE_SKILL_MAX_FILES = 50;
+export const WORKSPACE_SKILL_MAX_FILE_BYTES = 120_000;
+export const WORKSPACE_SKILL_MAX_BYTES = 1_000_000;
+function invalid(message) {
+    throw new OxygenError("invalid_workspace_skill", message, { exitCode: 2 });
+}
+export function workspaceSkillPath(path) {
+    if (typeof path !== "string" ||
+        path.length > 240 ||
+        !path ||
+        /[\\\u0000-\u001f\u007f]/u.test(path) ||
+        path
+            .split("/")
+            .some((part) => !part || part === "." || part === ".." || part.length > 120) ||
+        path.split("/").length > 15)
+        invalid("File paths must be relative, without empty segments, backslashes or traversal.");
+    return path;
+}
+export function validateWorkspaceSkillFile(file) {
+    const path = workspaceSkillPath(file?.path);
+    if (typeof file.content !== "string" || file.content.includes("\0"))
+        invalid(`File ${path} must contain text.`);
+    const bytes = new TextEncoder().encode(file.content).length;
+    if (bytes > WORKSPACE_SKILL_MAX_FILE_BYTES)
+        invalid(`File ${path} exceeds ${WORKSPACE_SKILL_MAX_FILE_BYTES} bytes.`);
+    return bytes;
+}
+/** Content stays verbatim. Names and paths are metadata, never tool authority. */
+export function parseWorkspaceSkillBundle(input) {
+    if (!Array.isArray(input.files) ||
+        input.files.length < 1 ||
+        input.files.length > WORKSPACE_SKILL_MAX_FILES)
+        invalid(`Provide 1–${WORKSPACE_SKILL_MAX_FILES} text files, including SKILL.md.`);
+    const paths = new Set();
+    let total = 0;
+    for (const file of input.files) {
+        const path = workspaceSkillPath(file?.path);
+        if (paths.has(path.toLowerCase()))
+            invalid(`Duplicate file path: ${path}`);
+        paths.add(path.toLowerCase());
+        total += validateWorkspaceSkillFile(file);
+    }
+    for (const path of paths) {
+        const parts = path.split("/");
+        for (let i = 1; i < parts.length; i++)
+            if (paths.has(parts.slice(0, i).join("/")))
+                invalid("A skill path cannot be both a file and a directory.");
+    }
+    if (total > WORKSPACE_SKILL_MAX_BYTES)
+        invalid(`Skill exceeds ${WORKSPACE_SKILL_MAX_BYTES} bytes.`);
+    const entry = input.files.find((file) => file.path === "SKILL.md");
+    if (!entry)
+        invalid("The skill must include a root SKILL.md file.");
+    const parsed = parseKnowledgeVaultMarkdown(entry.content);
+    if (parsed.frontmatterError)
+        invalid(`Invalid SKILL.md frontmatter: ${parsed.frontmatterError}`);
+    const name = input.name ?? parsed.properties.name;
+    const description = parsed.properties.description;
+    if (typeof name !== "string" ||
+        !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) ||
+        name.length > 64)
+        invalid("A skill name must contain 1–64 lowercase letters, digits or single hyphens.");
+    if (typeof description !== "string" ||
+        !description.trim() ||
+        description.length > 1_024)
+        invalid("SKILL.md needs a description in its YAML frontmatter (1–1024 characters).");
+    if (input.source_url !== undefined) {
+        let url;
+        try {
+            url = new URL(input.source_url);
+        }
+        catch {
+            invalid("source_url must be an HTTPS source URL.");
+        }
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            input.source_url.length > 2_000)
+            invalid("source_url must be an HTTPS source URL without credentials.");
+    }
+    return {
+        name,
+        description: description.trim(),
+        files: input.files.map((file) => ({ ...file })),
+        ...(input.source_url ? { source_url: input.source_url } : {}),
+    };
+}
+export function authorWorkspaceSkill(input) {
+    if (typeof input.instructions !== "string" || !input.instructions.trim())
+        invalid("Skill instructions are required.");
+    return parseWorkspaceSkillBundle({
+        name: input.name,
+        files: [
+            {
+                path: "SKILL.md",
+                content: `---\nname: ${JSON.stringify(input.name)}\ndescription: ${JSON.stringify(input.description)}\n---\n\n${input.instructions}\n`,
+            },
+        ],
+    });
+}

package/package.json

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