@forgeax/interface 0.4.1

package/dist/package/node/index.js

@@ -0,0 +1,2 @@
+/** Public package identity. Product startup remains on the explicit application entry. */
+export const INTERFACE_PACKAGE_NAME = '@forgeax/interface';

package/dist/package/node/lib/a11y-summary.js

@@ -0,0 +1,66 @@
+/** a11y-summary —— ui_snapshot 的未注册区域兜底(P1-13,评审 三.2)。
+ *
+ *  组件库自带的 role / aria-label 是免维护的 W3C 语义源:注册表管「调得动」,本模块
+ *  兜「看得见」——把 **不在 ActionRegistry 覆盖内** 的可见可交互元素汇成只读摘要,
+ *  让 AI 至少能定位「界面上还有什么」,再由人渐进登记。只读定向辅助:这些元素
+ *  **不能**经 ui_invoke 调用(契约 description 已写明)。
+ */
+const INTERACTIVE_SELECTOR = [
+    'button',
+    'a[href]',
+    'input',
+    'select',
+    'textarea',
+    '[role="button"]',
+    '[role="tab"]',
+    '[role="menuitem"]',
+    '[role="checkbox"]',
+    '[role="switch"]',
+    '[role="combobox"]',
+].join(', ');
+const MAX_ENTRIES = 120;
+function roleOf(el) {
+    return el.getAttribute('role') ?? el.tagName.toLowerCase();
+}
+function labelOf(el) {
+    return (el.getAttribute('aria-label')?.trim() ||
+        el.placeholder?.trim?.() ||
+        el.getAttribute('title')?.trim() ||
+        el.textContent?.trim().slice(0, 60) ||
+        '');
+}
+function isVisible(el) {
+    // offsetParent 为 null 覆盖 display:none 与 fixed 之外的大多数隐藏;够用且便宜。
+    return el.offsetParent !== null || el.tagName === 'BODY';
+}
+/** 汇总未注册区域的可交互元素(封顶 MAX_ENTRIES,超出标 truncated)。 */
+export function buildA11ySummary() {
+    if (typeof document === 'undefined')
+        return { entries: [], truncated: false };
+    const entries = [];
+    let truncated = false;
+    const seen = new Set();
+    for (const el of document.querySelectorAll(INTERACTIVE_SELECTOR)) {
+        if (el.closest('[data-fx-action]'))
+            continue; // 已在注册表覆盖内 → 归 actions,不重复
+        if (!isVisible(el))
+            continue;
+        const label = labelOf(el);
+        if (!label)
+            continue;
+        const key = `${roleOf(el)}|${label}`;
+        if (seen.has(key))
+            continue; // 同名同角色去重(列表行等重复元素只报一次)
+        seen.add(key);
+        if (entries.length >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        entries.push({
+            role: roleOf(el),
+            label,
+            ...(el.disabled ? { disabled: true } : {}),
+        });
+    }
+    return { entries, truncated };
+}

package/dist/package/node/lib/action-dom-discovery.js

@@ -0,0 +1,84 @@
+/** action-dom-discovery —— data-fx-action 声明式登记的**发现器**(评审 2.4)。
+ *
+ *  职责严格限定为「发现」:带 `data-fx-action="<id>"` 的元素挂载时自动
+ *  `registerAction`(handler = click 该元素),**不构成第二条执行路径**——派发仍统一走
+ *  action-registry 的 `dispatchAction` 单入口。目标元素不在 DOM(面板没开)时
+ *  `available()` 返回人话原因 fail-closed;**不做自动导航**——「把面板打开」本身该是
+ *  一个 action(如 page.open),导航编排属于模型,不藏进派发层。
+ *
+ *  可选注解:
+ *    data-fx-title        人读标题(缺省取 aria-label / textContent)
+ *    data-fx-description  AI 读说明
+ *    data-fx-capability   权限分级(8 类之一;缺省 'other'。危险按钮**务必**标
+ *                         delete/credential,编排层会据此弹确认卡)
+ */
+import { registerAction } from './action-registry.js';
+const VALID_CAPS = new Set([
+    'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
+]);
+/** id → 当前绑定的 DOM 元素(元素卸载后保留注册,available 报不可用;同 id 新元素挂载时重绑)。 */
+const boundEls = new Map();
+const registered = new Set();
+function titleFor(el, id) {
+    return (el.dataset.fxTitle?.trim() ||
+        el.getAttribute('aria-label')?.trim() ||
+        el.textContent?.trim().slice(0, 60) ||
+        id);
+}
+function bindElement(el) {
+    const id = el.dataset.fxAction?.trim();
+    if (!id)
+        return;
+    boundEls.set(id, el); // 同 id 新元素 → 重绑(注册项不变,available/run 经 map 取活引用)
+    if (registered.has(id))
+        return;
+    registered.add(id);
+    const capRaw = el.dataset.fxCapability?.trim() ?? '';
+    const capability = (VALID_CAPS.has(capRaw) ? capRaw : 'other');
+    registerAction({
+        id,
+        title: titleFor(el, id),
+        description: el.dataset.fxDescription?.trim() ||
+            `Click the "${titleFor(el, id)}" control (declared via data-fx-action).`,
+        schema: { type: 'object', properties: {} },
+        capability,
+        surface: 'ui',
+        available: () => {
+            const cur = boundEls.get(id);
+            return cur && cur.isConnected ? true : 'target element is not currently mounted (open its panel first)';
+        },
+        run: () => {
+            const cur = boundEls.get(id);
+            if (!cur || !cur.isConnected) {
+                return { status: 'rejected', reason: 'target element is not currently mounted' };
+            }
+            cur.click();
+            return { status: 'completed' };
+        },
+    });
+}
+function scan(root) {
+    if (!(root instanceof Element) && !(root instanceof Document))
+        return;
+    if (root instanceof Element && root.matches('[data-fx-action]'))
+        bindElement(root);
+    for (const el of root.querySelectorAll('[data-fx-action]'))
+        bindElement(el);
+}
+let started = false;
+/** 启动发现器(幂等)。初扫全文档 + MutationObserver 增量。 */
+export function startActionDomDiscovery() {
+    if (started || typeof document === 'undefined')
+        return;
+    started = true;
+    scan(document);
+    const mo = new MutationObserver((muts) => {
+        for (const m of muts) {
+            for (const node of m.addedNodes) {
+                if (node instanceof Element)
+                    scan(node);
+            }
+        }
+    });
+    mo.observe(document.documentElement, { childList: true, subtree: true });
+}

package/dist/package/node/lib/action-registry.js

@@ -0,0 +1,210 @@
+/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
+ *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
+ *
+ *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
+ *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
+ *    2. 命令面板(P2,cmdk 激活时数据源即本表);
+ *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
+ *       的 perception 往返接到编排层(@forgeax/orchestrator)。
+ *
+ *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
+ *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
+ *  本模块,manifest(`buildManifest`)只导出可序列化子集。
+ *
+ *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
+ *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
+ */
+// ─── 注册表本体(模块级 Map,页级单例)────────────────────────────────────────
+const actions = new Map();
+const stateSlices = new Map();
+const changeListeners = new Set();
+function notifyChange() {
+    for (const cb of changeListeners) {
+        try {
+            cb();
+        }
+        catch {
+            /* listener 异常不传染 */
+        }
+    }
+}
+/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
+export function registerAction(def) {
+    actions.set(def.id, def);
+    notifyChange();
+    return () => {
+        if (actions.get(def.id) === def) {
+            actions.delete(def.id);
+            notifyChange();
+        }
+    };
+}
+/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
+export function registerStateSlice(id, selector) {
+    stateSlices.set(id, selector);
+    notifyChange();
+    return () => {
+        if (stateSlices.get(id) === selector) {
+            stateSlices.delete(id);
+            notifyChange();
+        }
+    };
+}
+/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
+export function onRegistryChange(cb) {
+    changeListeners.add(cb);
+    return () => changeListeners.delete(cb);
+}
+export function getAction(id) {
+    return actions.get(id);
+}
+// ─── 派发单入口(评审 2.4:data-* 只做发现,执行永远走这里)──────────────────
+/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
+ *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
+ *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
+export const UI_ACTION_DISPATCH_EVENT = 'forgeax:ui-action-dispatch';
+/** 极简 JSON Schema 参数校验(P0:required + 顶层 properties 的原始类型)。
+ *  不引 ajv——契约漂移由编排层契约测试兜,这里挡住明显错参即可(Fail Fast)。 */
+function validateArgs(schema, args) {
+    if (!schema)
+        return true;
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const k of required) {
+        if (typeof k === 'string' && !(k in args))
+            return `missing required arg "${k}"`;
+    }
+    const props = schema.properties && typeof schema.properties === 'object'
+        ? schema.properties
+        : {};
+    for (const [k, v] of Object.entries(args)) {
+        const p = props[k];
+        if (!p)
+            continue; // 未声明的多余参数放过(向前兼容),由 run 自行忽略
+        const t = p.type;
+        if (typeof t === 'string') {
+            const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
+            const okType = (t === 'string' && actual === 'string') ||
+                (t === 'number' && actual === 'number') ||
+                (t === 'integer' && actual === 'number' && Number.isInteger(v)) ||
+                (t === 'boolean' && actual === 'boolean') ||
+                (t === 'object' && actual === 'object') ||
+                (t === 'array' && actual === 'array');
+            if (!okType)
+                return `arg "${k}" should be ${t}, got ${actual}`;
+        }
+        if (Array.isArray(p.enum) && !p.enum.includes(v)) {
+            return `arg "${k}" must be one of ${JSON.stringify(p.enum)}`;
+        }
+    }
+    return true;
+}
+/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
+export async function dispatchAction(id, args = {}, opts = {}) {
+    const src = opts.source ?? 'human';
+    // [fx-action-trace] 定位「点了/调了没反应」的最小充分打点:
+    //   ① entry —— 派发是否发生 + args/source(缺此行 = 根本没触发 dispatch)。
+    //   ② terminal —— 唯一终态行:completed/accepted 带 stateDigest(判「到底改了啥」),
+    //      rejected 带 reason(未注册/不可用/参数错/run 抛错 已统一收敛进 reason)。
+    // 两行即可定位:有 entry 无 terminal = 卡在 run();rejected+reason = 为何被拒;
+    // completed 但 stateDigest 没变 = action 效果与 UI 脱节。故只留这两点(+抛错补栈)。
+    console.info(`%c[fx-action]%c ▶ ${id} (${src})`, 'color:#818cf8;font-weight:bold', 'color:inherit', { args });
+    const done = (r) => {
+        if (r.status === 'rejected') {
+            console.warn(`[fx-action] ✗ ${id} rejected: ${r.reason ?? ''}`);
+        }
+        else {
+            console.info(`%c[fx-action]%c ✔ ${id} → ${r.status}`, 'color:#34d399;font-weight:bold', 'color:inherit', r.stateDigest !== undefined ? { stateDigest: r.stateDigest } : {});
+        }
+        return r;
+    };
+    const def = actions.get(id);
+    if (!def)
+        return done({ status: 'rejected', reason: `unknown action "${id}" (not in the registry)` });
+    const avail = def.available ? safeAvailable(def) : true;
+    if (avail !== true)
+        return done({ status: 'rejected', reason: avail });
+    const valid = validateArgs(def.schema, args);
+    if (valid !== true)
+        return done({ status: 'rejected', reason: valid });
+    try {
+        window.dispatchEvent(new CustomEvent(UI_ACTION_DISPATCH_EVENT, { detail: { id, source: src, args } }));
+    }
+    catch {
+        /* SSR / no window — ignore */
+    }
+    try {
+        const out = await def.run(args);
+        return done(out ?? { status: 'completed' });
+    }
+    catch (e) {
+        console.error(`[fx-action] ✗ ${id} threw`, e); // 抛错补一行栈(定位真异常)
+        return done({ status: 'rejected', reason: `action "${id}" threw: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+function safeAvailable(def) {
+    try {
+        return def.available();
+    }
+    catch (e) {
+        return `availability check threw: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
+ *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
+export function snapshotActions(detail, ids) {
+    const expand = detail === 'schema' ? new Set(ids ?? []) : null;
+    const out = [];
+    for (const def of actions.values()) {
+        const avail = def.available ? safeAvailable(def) : true;
+        const row = {
+            id: def.id,
+            title: def.title,
+            available: avail === true,
+            ...(avail === true ? {} : { reason: avail }),
+        };
+        if (expand?.has(def.id)) {
+            if (def.description)
+                row.description = def.description;
+            row.inputSchema = def.schema ?? { type: 'object', properties: {} };
+        }
+        out.push(row);
+    }
+    return out;
+}
+/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
+export function snapshotState() {
+    const out = {};
+    for (const [id, selector] of stateSlices) {
+        try {
+            out[id] = selector();
+        }
+        catch (e) {
+            out[id] = { error: `state slice threw: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    return out;
+}
+/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
+ *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
+export function buildManifest() {
+    const out = [];
+    for (const def of actions.values()) {
+        out.push({
+            id: def.id,
+            title: def.title,
+            ...(def.description ? { description: def.description } : {}),
+            inputSchema: def.schema ?? { type: 'object', properties: {} },
+            capability: def.capability,
+            ...(def.surface ? { surface: def.surface } : {}),
+            ...(def.timeoutMs ? { timeoutMs: def.timeoutMs } : {}),
+            ...(def.firstClass ? { firstClass: true } : {}),
+        });
+    }
+    return out;
+}
+/** 测试用:清空注册表(生产代码不要调)。 */
+export function __resetRegistryForTest() {
+    actions.clear();
+    stateSlices.clear();
+    changeListeners.clear();
+}

package/dist/package/node/lib/aegis.js

@@ -0,0 +1,230 @@
+// Aegis V2 — front-end observability reporting to the Galileo platform: JS /
+// Promise / resource errors, page performance, Web Vitals, static-resource
+// speed, PV+SPA route tracking, session timeline, and API monitoring with
+// `traceparent` injection for front↔back trace linking. Auto-instrumenting:
+// once `new Aegis(...)` runs it hooks window.onerror + unhandledrejection and
+// rewrites XHR/fetch itself; no per-call-site instrumentation.
+//
+// MIRROR SAFETY (load-bearing): this package has a public open-source mirror
+// whose publish pipeline scrubs + gates on internal hostnames. So NOTHING about
+// the SDK is hardcoded here — the CDN url, report endpoint, and project token
+// all arrive via build-time `import.meta.env.VITE_AEGIS_*`. With those unset
+// (the open-source / default case) every export below is an inert no-op and no
+// internal infra leaks into the committed source or the shipped bundle.
+//
+// Configure by dropping the three values into a gitignored `.env.local`; real
+// endpoint values live in the internal setup note, not in any committed file.
+// See `.env.example` for the (placeholder) shape.
+let instance = null;
+let started = false;
+/**
+ * Boot Aegis if — and only if — a project token is configured AND this is a
+ * production build. dev (`bun dev`) deliberately stays silent to keep the
+ * Galileo dataset clean; verify the wiring with `bun run build && bun run
+ * preview` (preview is a PROD build) or in the deployed web / desktop .app.
+ *
+ * Idempotent: StrictMode double-invokes and the two boot paths in main.tsx
+ * (detached surface + full shell) can both call this; the `started` latch makes
+ * the second call a no-op.
+ */
+export function initAegis() {
+    if (started)
+        return;
+    started = true;
+    // Gate: production builds only — dev (`bun dev`) stays silent to keep the
+    // dataset clean. Escape hatch for local verification: set VITE_AEGIS_DEV=1 in
+    // .env.local to also report in dev (use VITE_AEGIS_ENV=test there so the
+    // probe data lands in the test environment, not prod).
+    const devForce = import.meta.env.VITE_AEGIS_DEV === '1' || import.meta.env.VITE_AEGIS_DEV === 'true';
+    if (!import.meta.env.PROD && !devForce) {
+        console.info('[aegis] inert: dev build — set VITE_AEGIS_DEV=1 in .env.development/.env.local and RESTART the dev server');
+        return;
+    }
+    const id = import.meta.env.VITE_AEGIS_ID;
+    const sdkUrl = import.meta.env.VITE_AEGIS_SDK_URL;
+    const hostUrl = import.meta.env.VITE_AEGIS_HOST_URL;
+    if (!id || !sdkUrl || !hostUrl) {
+        console.warn('[aegis] inert: missing env (RESTART dev after editing .env*) —', {
+            id: !!id,
+            sdkUrl: !!sdkUrl,
+            hostUrl: !!hostUrl,
+        });
+        return; // unconfigured → stay inert
+    }
+    console.info('[aegis] loading SDK:', sdkUrl);
+    const script = document.createElement('script');
+    script.src = sdkUrl;
+    script.async = true;
+    // crossorigin lets the SDK read full stack traces from cross-origin scripts;
+    // without it window.onerror only sees "Script error." for foreign sources.
+    script.crossOrigin = 'anonymous';
+    script.onload = () => {
+        const Aegis = window.Aegis;
+        if (!Aegis) {
+            console.warn('[aegis] SDK script loaded but window.Aegis missing');
+            return;
+        }
+        try {
+            // URLs to inject the `traceparent` header into, for session front↔back
+            // trace linking. forgeax calls its backend same-origin (`/api`, `/ws`),
+            // and same-origin requests skip CORS preflight, so injecting there is
+            // safe. Override via VITE_AEGIS_TRACE_URLS (comma-separated regex source).
+            const traceUrlsEnv = import.meta.env.VITE_AEGIS_TRACE_URLS;
+            const injectTraceUrls = traceUrlsEnv
+                ? traceUrlsEnv.split(',').map((s) => new RegExp(s.trim()))
+                : [/\/api\//, /\/ws/];
+            instance = new Aegis({
+                id,
+                hostUrl: { url: hostUrl },
+                // 'production' → Galileo prod environment; anything else (test/personal)
+                // routes to the test environment. Defaults to production.
+                env: import.meta.env.VITE_AEGIS_ENV || 'production',
+                // Aggregation: everything enqueued within `delay` ms is merged into ONE
+                // /collect request. Aegis defaults to 1000ms which, on a chatty app
+                // (continuous /api polling via the api plugin + console bridge), fires a
+                // request almost every second. Widen the window to batch far more per
+                // request. Override via VITE_AEGIS_DELAY (ms). compress gzips the body
+                // (needs SDK >= 2.5.50) to cut bandwidth/cost on the bigger batches.
+                delay: Number(import.meta.env.VITE_AEGIS_DELAY) || 5000,
+                compress: true,
+                plugin: {
+                    // Identity / context collectors.
+                    aid: true,
+                    device: true,
+                    close: true,
+                    fId: false, // fingerprint — hurts perf, off unless needed
+                    ie: false,
+                    // Page-view + SPA route-change tracking.
+                    pv: true,
+                    spa: true,
+                    // Error capture (JS / Promise / resource).
+                    error: true,
+                    // Static-resource speed + page performance + Web Vitals.
+                    assetSpeed: true,
+                    pagePerformance: true,
+                    webVitals: true,
+                    // Session replay-style timeline; requires the Galileo collect host.
+                    session: true,
+                    // API monitoring (rewrites XHR/fetch) WITH trace-header injection for
+                    // front↔back session linking. apiDetail left off so request/response
+                    // bodies are NOT collected (lighter + privacy-safer).
+                    api: {
+                        injectTraceHeader: 'traceparent',
+                        injectTraceUrls,
+                    },
+                    reporting: false,
+                },
+            });
+            window.__forgeaxAegis = instance;
+            console.info('[aegis] initialized → reporting to', hostUrl, '(env:', import.meta.env.VITE_AEGIS_ENV || 'production', ')');
+            installConsoleBridge(instance);
+        }
+        catch (err) {
+            console.warn('[aegis] init failed:', err?.message ?? err);
+        }
+    };
+    script.onerror = () => {
+        console.warn('[aegis] SDK script failed to load:', sdkUrl);
+    };
+    document.head.appendChild(script);
+}
+/** Format one console arg into a loggable string (Errors keep their stack). */
+function fmtConsoleArg(a) {
+    if (typeof a === 'string')
+        return a;
+    if (a instanceof Error)
+        return `${a.message}\n${a.stack ?? ''}`;
+    try {
+        return JSON.stringify(a);
+    }
+    catch {
+        return String(a); // circular / non-serializable
+    }
+}
+let consoleBridged = false;
+/**
+ * Mirror browser `console.*` output into Galileo as logs, so the platform's log
+ * view shows runtime console output (not just auto-captured errors/perf). The
+ * original console still prints to DevTools — we wrap, not replace.
+ *
+ * Which levels forward is controlled by VITE_AEGIS_CONSOLE_LEVELS (comma-sep,
+ * default all: log,info,warn,error,debug; set "off" to disable, or e.g.
+ * "warn,error" to cut volume). console.error → aegis.error; the rest →
+ * aegis.info tagged with the original level.
+ *
+ * Volume note: forwarding ALL console output is high-traffic (engine/React spam)
+ * and bills against Galileo — narrow the levels if it gets noisy.
+ */
+function installConsoleBridge(aegis) {
+    if (consoleBridged)
+        return; // idempotent (StrictMode / re-init guards)
+    const cfg = (import.meta.env.VITE_AEGIS_CONSOLE_LEVELS ?? 'log,info,warn,error,debug').trim();
+    if (cfg === 'off' || cfg === '')
+        return;
+    consoleBridged = true;
+    const wanted = new Set(cfg.split(',').map((s) => s.trim()).filter(Boolean));
+    const methods = ['log', 'info', 'warn', 'error', 'debug'];
+    const c = console;
+    let reentrant = false; // Aegis may itself console.* on send failure — don't loop
+    for (const m of methods) {
+        if (!wanted.has(m))
+            continue;
+        const original = c[m].bind(console);
+        c[m] = (...args) => {
+            original(...args); // always keep DevTools output intact
+            if (reentrant)
+                return;
+            try {
+                const msg = args.map(fmtConsoleArg).join(' ');
+                if (!msg || msg.startsWith('[aegis]'))
+                    return; // skip our own diagnostics
+                reentrant = true;
+                if (m === 'error')
+                    aegis.error({ msg, from: 'console' });
+                else
+                    aegis.info({ msg, from: 'console', consoleLevel: m });
+            }
+            catch {
+                /* never let logging crash the app */
+            }
+            finally {
+                reentrant = false;
+            }
+        };
+    }
+}
+/**
+ * Report a React-render error. React error boundaries swallow render throws
+ * before they reach window.onerror, so Aegis' auto JS-error capture never sees
+ * them — this bridges that gap. No-op until the SDK instance is live (early
+ * pre-load boundary catches are rare and still surface in the console).
+ */
+export function reportError(error, componentStack, scope) {
+    if (!instance)
+        return;
+    try {
+        instance.error({
+            msg: `[${scope ?? 'react'}] ${error.message}`,
+            stack: error.stack ?? '',
+            componentStack: componentStack ?? '',
+        });
+    }
+    catch {
+        /* never let telemetry crash the error path */
+    }
+}
+/**
+ * Attach the current user's id once known. uid is often not available at boot,
+ * so call this after auth/session resolves; Aegis backfills it on every
+ * subsequent report. No-op until the SDK instance is live.
+ */
+export function setAegisUid(uid) {
+    if (!instance || !uid)
+        return;
+    try {
+        instance.setConfig({ uid });
+    }
+    catch {
+        /* no-op */
+    }
+}

package/dist/package/node/lib/agent-catalog-url.js

@@ -0,0 +1,24 @@
+import { getLocale } from '../i18n/index.js';
+/** Current UI locale for Agent Catalog query params. */
+export function agentCatalogLang() {
+    return getLocale();
+}
+/** Build a locale-aligned Agent Catalog query string. */
+export function agentCatalogQuery(extra) {
+    const params = new URLSearchParams({ lang: getLocale() });
+    if (extra) {
+        for (const [k, v] of Object.entries(extra)) {
+            if (v !== undefined && v !== '')
+                params.set(k, v);
+        }
+    }
+    return params.toString();
+}
+/** Build `/api/agents` with `lang` aligned to Studio locale. */
+export function agentCatalogUrl(extra) {
+    return `/api/agents?${agentCatalogQuery(extra)}`;
+}
+/** Build the locale-aware recent Agent activity URL. */
+export function agentEventsRecentUrl(limit = 30) {
+    return `/api/agents/events/recent?limit=${limit}&lang=${getLocale()}`;
+}