@cavi-ai/api-client 0.1.0

package/dist/core/data/guards.d.ts

@@ -0,0 +1,6 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asString(value: unknown): string | null;
+export declare function asNumber(value: unknown): number | null;
+export declare function asStringArray(value: unknown): string[];
+export declare function asBoolean(value: unknown): boolean | null;
+//# sourceMappingURL=guards.d.ts.map

package/dist/core/data/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/core/data/guards.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAItD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEtD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAOtD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAExD"}

package/dist/core/data/guards.js

@@ -0,0 +1,22 @@
+export function isRecord(value) {
+    return Boolean(value) && typeof value === "object";
+}
+export function asString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : null;
+}
+export function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => asString(entry))
+        .filter((entry) => Boolean(entry));
+}
+export function asBoolean(value) {
+    return typeof value === "boolean" ? value : null;
+}

package/dist/core/data/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./guards.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/data/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/core/data/index.js

@@ -0,0 +1 @@
+export * from "./guards.js";

package/dist/core/env/config.d.ts

@@ -0,0 +1,40 @@
+export type HttpApiEnvSource = Record<string, string | undefined>;
+export type HttpApiSurfaceConfig = {
+    baseUrl: string;
+    authToken: string | null;
+    clientId: string;
+};
+/** Primary env-var names for one HTTP surface. */
+export type HttpSurfaceEnvKeys = {
+    baseUrl: string;
+    authToken: string;
+    clientId: string;
+};
+/** Fallback env-var names checked (in order) when the primary key is unset. */
+export type HttpSurfaceEnvAliases = {
+    baseUrl?: readonly string[];
+    authToken?: readonly string[];
+    clientId?: readonly string[];
+};
+/** Last-resort values used when neither the primary nor any alias env var is set. */
+export type HttpSurfaceEnvFallback = {
+    baseUrl: string;
+    authToken?: string | null;
+    clientId: string;
+};
+export type HttpSurfaceEnvSpec = {
+    keys: HttpSurfaceEnvKeys;
+    aliases?: HttpSurfaceEnvAliases;
+    fallback: HttpSurfaceEnvFallback;
+};
+export type ResolveHttpSurfaceConfigOptions = {
+    defaults?: Partial<HttpApiSurfaceConfig>;
+    trimValues?: boolean;
+    includeAliases?: boolean;
+};
+/**
+ * Resolve a single HTTP surface's config from an env bag.
+ * Precedence per field: primary key → aliases → caller `defaults` → spec `fallback`.
+ */
+export declare function resolveHttpSurfaceConfigFromEnv(env: HttpApiEnvSource, spec: HttpSurfaceEnvSpec, options?: ResolveHttpSurfaceConfigOptions): HttpApiSurfaceConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/env/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/env/config.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AA6BF;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,+BAAoC,GAC5C,oBAAoB,CActB"}

package/dist/core/env/config.js

@@ -0,0 +1,44 @@
+// Gateway-agnostic env resolution primitive. Core knows how to read a single
+// HTTP surface's config from an env bag with primary keys + ordered aliases +
+// caller-supplied fallbacks. It deliberately knows NOTHING about any specific
+// domain, provider, or surface/env-var name or default — those live in the
+// owning layer (extensions/cavi, providers/*) which composes this primitive.
+function clean(value, trim) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = trim ? value.trim() : value;
+    return cleaned || undefined;
+}
+function firstEnvValue(env, primary, aliases, trim, includeAliases) {
+    const primaryValue = clean(env[primary], trim);
+    if (primaryValue !== undefined)
+        return primaryValue;
+    if (!includeAliases)
+        return undefined;
+    for (const alias of aliases) {
+        const value = clean(env[alias], trim);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+function cleanToken(value) {
+    return value || null;
+}
+/**
+ * Resolve a single HTTP surface's config from an env bag.
+ * Precedence per field: primary key → aliases → caller `defaults` → spec `fallback`.
+ */
+export function resolveHttpSurfaceConfigFromEnv(env, spec, options = {}) {
+    const trim = options.trimValues ?? true;
+    const includeAliases = options.includeAliases ?? true;
+    const defaults = options.defaults;
+    const baseUrl = firstEnvValue(env, spec.keys.baseUrl, spec.aliases?.baseUrl ?? [], trim, includeAliases);
+    const authToken = firstEnvValue(env, spec.keys.authToken, spec.aliases?.authToken ?? [], trim, includeAliases);
+    const clientId = firstEnvValue(env, spec.keys.clientId, spec.aliases?.clientId ?? [], trim, includeAliases);
+    return {
+        baseUrl: baseUrl ?? defaults?.baseUrl ?? spec.fallback.baseUrl,
+        authToken: cleanToken(authToken) ?? defaults?.authToken ?? spec.fallback.authToken ?? null,
+        clientId: clientId ?? defaults?.clientId ?? spec.fallback.clientId,
+    };
+}

package/dist/core/env/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./config.js";
+export * from "./repo-root.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/env/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/core/env/index.js

@@ -0,0 +1,2 @@
+export * from "./config.js";
+export * from "./repo-root.js";

package/dist/core/env/repo-root.d.ts

@@ -0,0 +1,11 @@
+export declare const REPO_ROOT_ENV_KEY: "REPO_ROOT";
+export declare const GLOBAL_REPO_ROOT_KEY: "__CAVI_REPO_ROOT__";
+export type RepoRootEnv = Record<string, string | undefined>;
+export type ResolveRepoRootOptions = {
+    repoRoot?: string | null;
+    env?: RepoRootEnv;
+    globalRepoRoot?: string | null;
+};
+export declare function resolveRepoRoot(options?: ResolveRepoRootOptions): string | null;
+export declare function requireRepoRoot(options?: ResolveRepoRootOptions): string;
+//# sourceMappingURL=repo-root.d.ts.map

package/dist/core/env/repo-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-root.d.ts","sourceRoot":"","sources":["../../../src/core/env/repo-root.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,EAAG,WAAoB,CAAC;AACtD,eAAO,MAAM,oBAAoB,EAAG,oBAA6B,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE7D,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAiCF,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,GAAG,IAAI,CAQnF;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAM5E"}

package/dist/core/env/repo-root.js

@@ -0,0 +1,36 @@
+export const REPO_ROOT_ENV_KEY = "REPO_ROOT";
+export const GLOBAL_REPO_ROOT_KEY = "__CAVI_REPO_ROOT__";
+function cleanRepoRoot(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.replace(/\/+$/, "") : null;
+}
+function readProcessEnv() {
+    try {
+        return typeof process !== "undefined" && process.env ? process.env : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readGlobalRepoRoot() {
+    try {
+        return cleanRepoRoot(globalThis[GLOBAL_REPO_ROOT_KEY]);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveRepoRoot(options = {}) {
+    return (cleanRepoRoot(options.repoRoot) ??
+        cleanRepoRoot(options.env?.[REPO_ROOT_ENV_KEY]) ??
+        cleanRepoRoot(options.globalRepoRoot) ??
+        readGlobalRepoRoot() ??
+        cleanRepoRoot(readProcessEnv()[REPO_ROOT_ENV_KEY]));
+}
+export function requireRepoRoot(options = {}) {
+    const repoRoot = resolveRepoRoot(options);
+    if (!repoRoot) {
+        throw new Error("Missing REPO_ROOT for @cavi-ai/api-client filesystem integration");
+    }
+    return repoRoot;
+}

package/dist/core/gateway/agent/commands.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Gateway-agnostic chat slash-command + mention parsing.
+ *
+ * The authoritative command catalog is owned by the gateway and surfaced on the
+ * capabilities snapshot (`capabilities.commands`). Use {@link extractGatewayCommandCatalog}
+ * to read it and pass the result as the `coreCommands` option so built-ins stay
+ * dynamic rather than manually maintained. {@link FALLBACK_CORE_SLASH_COMMANDS}
+ * is an offline-only safety net used when the gateway snapshot is unavailable.
+ */
+export type AgentCommandShortcut = {
+    id: string;
+    label: string;
+    insert: string;
+    description?: string;
+};
+export type AgentMentionSuggestion = {
+    id: string;
+    label: string;
+    insert: string;
+};
+export type AgentCommandSource = {
+    id?: string | null;
+    name?: string | null;
+    commands?: unknown;
+    slashCommands?: unknown;
+    slash_commands?: unknown;
+    commandRegistry?: unknown;
+    command_registry?: unknown;
+    routing?: unknown;
+    config?: unknown;
+    snapshot?: unknown;
+    orchestration?: unknown;
+    triggers?: readonly unknown[] | null;
+};
+export type AgentCommandSurface = {
+    slashShortcuts: AgentCommandShortcut[];
+    mentionChips: AgentMentionSuggestion[];
+};
+/** Shape of a single entry in the gateway capabilities `commands` catalog. */
+export type GatewayCommandSpec = {
+    command?: string;
+    name?: string;
+    id?: string;
+    insert?: string;
+    template?: string;
+    description?: string;
+    summary?: string;
+    help?: string;
+    category?: string;
+    aliases?: readonly string[];
+    params?: readonly Record<string, unknown>[];
+    arguments?: readonly Record<string, unknown>[];
+    examples?: readonly string[];
+    enabled?: boolean;
+    source?: string;
+    scope?: string;
+    metadata?: Record<string, unknown>;
+};
+export type GatewayCommandCatalog = readonly (GatewayCommandSpec | string)[] | {
+    commands?: unknown;
+    slashCommands?: unknown;
+    slash_commands?: unknown;
+    core?: unknown;
+    agent?: unknown;
+    teams?: unknown;
+};
+export type GatewayCommandCapabilities = {
+    commands?: GatewayCommandCatalog;
+    slashCommands?: GatewayCommandCatalog;
+    slash_commands?: GatewayCommandCatalog;
+    commandCatalog?: GatewayCommandCatalog;
+    command_catalog?: GatewayCommandCatalog;
+};
+/**
+ * Offline-only fallback for the gateway built-in slash commands. The live
+ * catalog comes from {@link extractGatewayCommandCatalog}; this is only used
+ * when the capabilities snapshot has not been fetched yet.
+ */
+export declare const FALLBACK_CORE_SLASH_COMMANDS: readonly AgentCommandShortcut[];
+/**
+ * Read the gateway built-in command catalog from a capabilities snapshot
+ * (`capabilities.commands`). Returns an empty list when the gateway has not
+ * surfaced a catalog yet, so callers can decide whether to fall back.
+ */
+export declare function extractGatewayCommandCatalog(capabilities: unknown): AgentCommandShortcut[];
+export type BuildAgentSlashShortcutsOptions = {
+    /** Gateway built-ins (from {@link extractGatewayCommandCatalog}); defaults to the offline fallback. */
+    coreCommands?: readonly AgentCommandShortcut[];
+};
+export declare function buildAgentSlashShortcuts(agent: AgentCommandSource | null | undefined, options?: BuildAgentSlashShortcutsOptions): AgentCommandShortcut[];
+export declare function buildAgentMentionChips(agent: AgentCommandSource | null | undefined): AgentMentionSuggestion[];
+export declare function buildAgentCommandSurface(agent: AgentCommandSource | null | undefined, options?: BuildAgentSlashShortcutsOptions): AgentCommandSurface;
+//# sourceMappingURL=commands.d.ts.map

package/dist/core/gateway/agent/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/agent/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,EAAE,oBAAoB,EAAE,CAAC;IACvC,YAAY,EAAE,sBAAsB,EAAE,CAAC;CACxC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC5C,SAAS,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC/C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B,SAAS,CAAC,kBAAkB,GAAG,MAAM,CAAC,EAAE,GACxC;IACE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEN,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,oBAAoB,EAiBvE,CAAC;AAgSF;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,OAAO,GAAG,oBAAoB,EAAE,CAuC1F;AAED,MAAM,MAAM,+BAA+B,GAAG;IAC5C,uGAAuG;IACvG,YAAY,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAChD,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EAC5C,OAAO,GAAE,+BAAoC,GAC5C,oBAAoB,EAAE,CAYxB;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAC3C,sBAAsB,EAAE,CAQ1B;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EAC5C,OAAO,GAAE,+BAAoC,GAC5C,mBAAmB,CAKrB"}

package/dist/core/gateway/agent/commands.js

@@ -0,0 +1,351 @@
+/**
+ * Gateway-agnostic chat slash-command + mention parsing.
+ *
+ * The authoritative command catalog is owned by the gateway and surfaced on the
+ * capabilities snapshot (`capabilities.commands`). Use {@link extractGatewayCommandCatalog}
+ * to read it and pass the result as the `coreCommands` option so built-ins stay
+ * dynamic rather than manually maintained. {@link FALLBACK_CORE_SLASH_COMMANDS}
+ * is an offline-only safety net used when the gateway snapshot is unavailable.
+ */
+/**
+ * Offline-only fallback for the gateway built-in slash commands. The live
+ * catalog comes from {@link extractGatewayCommandCatalog}; this is only used
+ * when the capabilities snapshot has not been fetched yet.
+ */
+export const FALLBACK_CORE_SLASH_COMMANDS = [
+    { id: "help", label: "/help", insert: "/help", description: "Short help summary from the gateway" },
+    { id: "commands", label: "/commands", insert: "/commands", description: "Live command catalog for this session" },
+    { id: "agent", label: "/agent", insert: "/agent ", description: "Show or switch the active agent" },
+    { id: "session", label: "/session", insert: "/session", description: "Show the current session binding" },
+    { id: "status", label: "/status", insert: "/status", description: "Gateway, runtime, and provider usage status" },
+    { id: "tools", label: "/tools", insert: "/tools", description: "Tools the active agent can use right now" },
+    { id: "new", label: "/new", insert: "/new", description: "Start a new session (alias: /reset)" },
+    { id: "stop", label: "/stop", insert: "/stop", description: "Abort the current run" },
+    { id: "model", label: "/model", insert: "/model", description: "Show or set the active model" },
+    { id: "think", label: "/think", insert: "/think ", description: "Set thinking level (e.g. low|medium|high)" },
+    { id: "verbose", label: "/verbose", insert: "/verbose ", description: "Toggle verbose output (on|off|full)" },
+    { id: "queue", label: "/queue", insert: "/queue ", description: "Manage queue behavior (steer|interrupt|...)" },
+    { id: "skill", label: "/skill", insert: "/skill ", description: "Run a skill by name" },
+    { id: "focus", label: "/focus", insert: "/focus ", description: "Bind this thread to an agent target" },
+    { id: "unfocus", label: "/unfocus", insert: "/unfocus", description: "Remove the current thread binding" },
+    { id: "whoami", label: "/whoami", insert: "/whoami", description: "Show your sender id" },
+];
+function cleanString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function cleanInsertString(value) {
+    return typeof value === "string" ? value.trimStart() : "";
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stableSlug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 72) || "command";
+}
+function commandHead(value) {
+    return value.split(/\s+/u)[0] ?? value;
+}
+function agentLabel(agent) {
+    return cleanString(agent?.name) || cleanString(agent?.id) || "agent";
+}
+function firstString(record, keys) {
+    for (const key of keys) {
+        const value = cleanString(record[key]);
+        if (value)
+            return value;
+    }
+    return "";
+}
+function firstInsertString(record, keys) {
+    for (const key of keys) {
+        const value = cleanInsertString(record[key]);
+        if (value.trim())
+            return value;
+    }
+    return "";
+}
+function normalizeSlashTrigger(agent, raw) {
+    const trigger = cleanString(raw);
+    if (!trigger.startsWith("/"))
+        return null;
+    const label = commandHead(trigger);
+    if (label.length <= 1)
+        return null;
+    const suffix = trigger.slice(label.length).trim();
+    const agentId = cleanString(agent?.id) || agentLabel(agent);
+    return {
+        id: `agent_${stableSlug(agentId)}_${stableSlug(trigger)}`,
+        label,
+        insert: trigger.endsWith(" ") ? trigger : suffix ? trigger : label,
+        description: suffix
+            ? `${agentLabel(agent)} preset: ${suffix}`
+            : `${agentLabel(agent)} command`,
+    };
+}
+const COMMAND_VALUE_KEYS = [
+    "command",
+    "cmd",
+    "slashCommand",
+    "slash_command",
+    "insert",
+    "template",
+    "prefill",
+    "value",
+    "name",
+    "id",
+];
+const COMMAND_DESCRIPTION_KEYS = [
+    "description",
+    "summary",
+    "help",
+    "hint",
+    "label",
+];
+const COMMAND_SOURCE_KEYS = [
+    "commands",
+    "slashCommands",
+    "slash_commands",
+    "commandRegistry",
+    "command_registry",
+    "command",
+    "cmd",
+    "slashCommand",
+    "slash_command",
+    "commandModifier",
+    "command_modifier",
+];
+const COMMAND_SECTION_KEYS = [
+    "routing",
+    "config",
+    "snapshot",
+    "orchestration",
+    "metadata",
+    "profile",
+];
+const MENTION_SOURCE_KEYS = [
+    "triggers",
+    "mentions",
+    "mentionTriggers",
+    "mention_triggers",
+    "aliases",
+    "keywords",
+];
+function normalizeSlashCommandEntry(agent, raw) {
+    if (typeof raw === "string") {
+        return normalizeSlashTrigger(agent, raw);
+    }
+    if (!isRecord(raw)) {
+        return null;
+    }
+    const insertCandidate = firstInsertString(raw, ["insert", "template", "prefill"]);
+    const commandCandidate = firstString(raw, COMMAND_VALUE_KEYS);
+    const command = insertCandidate.startsWith("/")
+        ? insertCandidate
+        : commandCandidate.startsWith("/")
+            ? commandCandidate
+            : "";
+    const shortcut = normalizeSlashTrigger(agent, command);
+    if (!shortcut)
+        return null;
+    const description = firstString(raw, COMMAND_DESCRIPTION_KEYS);
+    if (!description || description.startsWith("/")) {
+        return shortcut;
+    }
+    return {
+        ...shortcut,
+        description,
+    };
+}
+function collectCommandEntries(value, out) {
+    if (value == null)
+        return;
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectCommandEntries(entry, out);
+        return;
+    }
+    if (!isRecord(value)) {
+        out.push(value);
+        return;
+    }
+    if (COMMAND_VALUE_KEYS.some((key) => cleanString(value[key]))) {
+        out.push(value);
+        return;
+    }
+    for (const entry of Object.values(value)) {
+        collectCommandEntries(entry, out);
+    }
+}
+function collectCapabilityCommandEntries(value, out) {
+    if (value == null)
+        return;
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            collectCapabilityCommandEntries(entry, out);
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        out.push(value);
+        return;
+    }
+    if (COMMAND_VALUE_KEYS.some((key) => cleanString(value[key]))) {
+        out.push(value);
+        return;
+    }
+    for (const key of [
+        "commands",
+        "slashCommands",
+        "slash_commands",
+        "core",
+        "agent",
+        "teams",
+    ]) {
+        collectCapabilityCommandEntries(value[key], out);
+    }
+}
+function collectCommandSections(value, out, depth = 0) {
+    if (!isRecord(value) || depth > 3)
+        return;
+    for (const key of COMMAND_SOURCE_KEYS) {
+        collectCommandEntries(value[key], out);
+    }
+    for (const key of COMMAND_SECTION_KEYS) {
+        collectCommandSections(value[key], out, depth + 1);
+    }
+}
+function collectSlashCommandEntries(agent) {
+    const out = [];
+    collectCommandEntries(agent?.triggers, out);
+    collectCommandSections(agent, out);
+    const agentId = cleanString(agent?.id);
+    if (agentId) {
+        const label = agentLabel(agent);
+        out.push({
+            command: `/agent ${agentId}`,
+            description: `Switch command context to ${label}`,
+        }, {
+            command: `/focus ${agentId}`,
+            description: `Bind this thread to ${label}`,
+        });
+    }
+    return out;
+}
+function collectMentionEntries(agent) {
+    const out = [];
+    if (!isRecord(agent)) {
+        return out;
+    }
+    const record = agent;
+    for (const key of MENTION_SOURCE_KEYS) {
+        collectCommandEntries(record[key], out);
+    }
+    return out;
+}
+function normalizeMentionTrigger(agent, raw) {
+    const trigger = cleanString(raw);
+    if (!trigger || trigger.startsWith("/"))
+        return null;
+    const agentId = cleanString(agent?.id) || agentLabel(agent);
+    return {
+        id: `mention_${stableSlug(agentId)}_${stableSlug(trigger)}`,
+        label: trigger,
+        insert: trigger.endsWith(" ") ? trigger : `${trigger} `,
+    };
+}
+function pushUniqueShortcut(out, seen, shortcut) {
+    const key = `${shortcut.label.toLowerCase()}${shortcut.insert.toLowerCase()}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    out.push(shortcut);
+}
+function pushUniqueMention(out, seen, chip) {
+    const key = chip.insert.trim().toLowerCase();
+    if (!key || seen.has(key))
+        return;
+    seen.add(key);
+    out.push(chip);
+}
+/**
+ * Read the gateway built-in command catalog from a capabilities snapshot
+ * (`capabilities.commands`). Returns an empty list when the gateway has not
+ * surfaced a catalog yet, so callers can decide whether to fall back.
+ */
+export function extractGatewayCommandCatalog(capabilities) {
+    if (!isRecord(capabilities))
+        return [];
+    const entries = [];
+    for (const key of [
+        "commands",
+        "slashCommands",
+        "slash_commands",
+        "commandCatalog",
+        "command_catalog",
+        "features",
+    ]) {
+        collectCapabilityCommandEntries(capabilities[key], entries);
+    }
+    if (entries.length === 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const entry of entries) {
+        const command = typeof entry === "string"
+            ? cleanString(entry)
+            : isRecord(entry)
+                ? firstInsertString(entry, ["command", "name", "id", "insert", "template", "prefill"])
+                : "";
+        const insert = command.startsWith("/") ? command : command ? `/${command}` : "";
+        if (!insert)
+            continue;
+        const label = commandHead(insert);
+        if (label.length <= 1)
+            continue;
+        const description = isRecord(entry)
+            ? firstString(entry, COMMAND_DESCRIPTION_KEYS)
+            : "";
+        const shortcut = {
+            id: `core_${stableSlug(insert)}`,
+            label,
+            insert,
+            ...(description && !description.startsWith("/") ? { description } : {}),
+        };
+        pushUniqueShortcut(out, seen, shortcut);
+    }
+    return out;
+}
+export function buildAgentSlashShortcuts(agent, options = {}) {
+    const core = options.coreCommands ?? FALLBACK_CORE_SLASH_COMMANDS;
+    const seen = new Set();
+    const out = [];
+    for (const shortcut of core) {
+        pushUniqueShortcut(out, seen, shortcut);
+    }
+    for (const entry of collectSlashCommandEntries(agent)) {
+        const shortcut = normalizeSlashCommandEntry(agent, entry);
+        if (shortcut)
+            pushUniqueShortcut(out, seen, shortcut);
+    }
+    return out;
+}
+export function buildAgentMentionChips(agent) {
+    const seen = new Set();
+    const out = [];
+    for (const trigger of collectMentionEntries(agent)) {
+        const chip = normalizeMentionTrigger(agent, trigger);
+        if (chip)
+            pushUniqueMention(out, seen, chip);
+    }
+    return out;
+}
+export function buildAgentCommandSurface(agent, options = {}) {
+    return {
+        slashShortcuts: buildAgentSlashShortcuts(agent, options),
+        mentionChips: buildAgentMentionChips(agent),
+    };
+}