@molecule/app-ide-react 1.0.0

package/dist/components/chat-cost-utilities.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure helpers backing the `/cost` command card.
+ *
+ * The card renders what `GET /projects/:id/chat-usage` returns for the current
+ * conversation. The one thing that is NOT obvious from the payload — and that
+ * made the card look broken next to a provider dashboard — is what
+ * `inputTokens` means:
+ *
+ * - Every AI bond normalizes usage into **disjoint** buckets: `inputTokens`
+ *   (uncached prompt), `cacheReadInputTokens` (cache hits) and
+ *   `cacheCreationInputTokens` (cache writes). On OpenAI-compatible APIs
+ *   (DeepSeek, Alibaba, Moonshot) the wire format is the opposite — `prompt_tokens`
+ *   is the TOTAL and `prompt_tokens_details.cached_tokens` is a subset of it — so
+ *   those bonds subtract before reporting. Anthropic already reports them
+ *   separately and nothing is subtracted.
+ * - A provider's usage dashboard reports **total tokens processed**, cache hits
+ *   included. So `inputTokens` alone is not comparable to it, and in a long
+ *   agentic turn (where each iteration replays the whole conversation against a
+ *   warm cache) the cached share is the overwhelming majority of the volume.
+ *
+ * {@link totalPromptTokens} is therefore the figure to compare against a provider
+ * dashboard, and {@link formatTokenTotal} is the shared abbreviation used on the
+ * card. Both are deterministic and side-effect free so they can be unit tested
+ * without rendering or a real backend; the component supplies `t()`.
+ *
+ * @module
+ */
+/** The usage-shaped subset of `GET /projects/:id/chat-usage` the cost card reads. */
+export interface ChatUsageTokens {
+    /** Uncached prompt tokens. NOT the provider's `prompt_tokens` — cache hits are excluded. */
+    inputTokens: number;
+    /** Generated tokens. */
+    outputTokens: number;
+    /** Prompt tokens served from the provider's cache. */
+    cacheReadInputTokens?: number;
+    /** Prompt tokens written into the provider's cache. */
+    cacheCreationInputTokens?: number;
+}
+/**
+ * Abbreviate a token count for display (`1.2M`, `340.5K`, `812`).
+ *
+ * @param n - The token count.
+ * @returns The abbreviated string.
+ */
+export declare function formatTokenTotal(n: number): string;
+/**
+ * Total CACHED prompt tokens — reads plus writes.
+ *
+ * @param usage - The usage payload.
+ * @returns The combined cached-token count (0 when the provider reports none).
+ */
+export declare function cachedPromptTokens(usage: ChatUsageTokens): number;
+/**
+ * Total prompt tokens the provider actually processed — uncached + cached. This
+ * is the figure that lines up with a provider usage dashboard; `inputTokens` on
+ * its own does not, because the bonds report the buckets disjointly.
+ *
+ * @param usage - The usage payload.
+ * @returns Uncached input plus every cached prompt token.
+ */
+export declare function totalPromptTokens(usage: ChatUsageTokens): number;
+//# sourceMappingURL=chat-cost-utilities.d.ts.map

package/dist/components/chat-cost-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-cost-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-cost-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,sDAAsD;IACtD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,uDAAuD;IACvD,wBAAwB,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAIjE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAGhE"}

package/dist/components/chat-cost-utilities.js

@@ -0,0 +1,66 @@
+/**
+ * Pure helpers backing the `/cost` command card.
+ *
+ * The card renders what `GET /projects/:id/chat-usage` returns for the current
+ * conversation. The one thing that is NOT obvious from the payload — and that
+ * made the card look broken next to a provider dashboard — is what
+ * `inputTokens` means:
+ *
+ * - Every AI bond normalizes usage into **disjoint** buckets: `inputTokens`
+ *   (uncached prompt), `cacheReadInputTokens` (cache hits) and
+ *   `cacheCreationInputTokens` (cache writes). On OpenAI-compatible APIs
+ *   (DeepSeek, Alibaba, Moonshot) the wire format is the opposite — `prompt_tokens`
+ *   is the TOTAL and `prompt_tokens_details.cached_tokens` is a subset of it — so
+ *   those bonds subtract before reporting. Anthropic already reports them
+ *   separately and nothing is subtracted.
+ * - A provider's usage dashboard reports **total tokens processed**, cache hits
+ *   included. So `inputTokens` alone is not comparable to it, and in a long
+ *   agentic turn (where each iteration replays the whole conversation against a
+ *   warm cache) the cached share is the overwhelming majority of the volume.
+ *
+ * {@link totalPromptTokens} is therefore the figure to compare against a provider
+ * dashboard, and {@link formatTokenTotal} is the shared abbreviation used on the
+ * card. Both are deterministic and side-effect free so they can be unit tested
+ * without rendering or a real backend; the component supplies `t()`.
+ *
+ * @module
+ */
+/**
+ * Abbreviate a token count for display (`1.2M`, `340.5K`, `812`).
+ *
+ * @param n - The token count.
+ * @returns The abbreviated string.
+ */
+export function formatTokenTotal(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0';
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(Math.round(n));
+}
+/**
+ * Total CACHED prompt tokens — reads plus writes.
+ *
+ * @param usage - The usage payload.
+ * @returns The combined cached-token count (0 when the provider reports none).
+ */
+export function cachedPromptTokens(usage) {
+    const read = usage.cacheReadInputTokens ?? 0;
+    const write = usage.cacheCreationInputTokens ?? 0;
+    return (Number.isFinite(read) ? read : 0) + (Number.isFinite(write) ? write : 0);
+}
+/**
+ * Total prompt tokens the provider actually processed — uncached + cached. This
+ * is the figure that lines up with a provider usage dashboard; `inputTokens` on
+ * its own does not, because the bonds report the buckets disjointly.
+ *
+ * @param usage - The usage payload.
+ * @returns Uncached input plus every cached prompt token.
+ */
+export function totalPromptTokens(usage) {
+    const input = Number.isFinite(usage.inputTokens) ? usage.inputTokens : 0;
+    return input + cachedPromptTokens(usage);
+}
+//# sourceMappingURL=chat-cost-utilities.js.map

package/dist/components/chat-cost-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-cost-utilities.js","sourceRoot":"","sources":["../../src/components/chat-cost-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAA;IAC7C,IAAI,CAAC,IAAI,SAAS;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAA;IAC3D,IAAI,CAAC,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAA;IACnD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAsB;IACvD,MAAM,IAAI,GAAG,KAAK,CAAC,oBAAoB,IAAI,CAAC,CAAA;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,wBAAwB,IAAI,CAAC,CAAA;IACjD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAClF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IACxE,OAAO,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;AAC1C,CAAC"}

package/dist/components/chat-effort-utilities.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure helpers backing the `/effort` command and its status view.
+ *
+ * Effort is persisted PER MODE (`settings.effortByMode`, with the legacy single
+ * `settings.effortLevel` as fallback) as the model's OWN native value — there is
+ * no abstract scale. Users see and type the ACTIVE MODEL's own effort values
+ * (`xhigh` on Claude Opus 4.8, `medium` on Grok 4.3, `16K` thinking tokens on
+ * budget-configurable models …), which vary per model and therefore per mode:
+ * plan and execute run different models, so each mode carries its own value
+ * chosen from its own model's levels.
+ *
+ * Command shapes:
+ * - `/effort` or `/effort ?` — status for every mode.
+ * - `/effort <value>` — set the CURRENT mode's effort to a native value.
+ * - `/effort --plan <value>` / `/effort --execute <value>` — set a specific
+ *   mode's effort (mirrors `/model --plan` / `--execute`).
+ *
+ * Deterministic and side-effect free — unit testable without rendering or a
+ * backend. User-facing prose lives in the component via `t()`.
+ *
+ * @module
+ */
+import type { AppModelDefinition, EffortLevel, EffortOption } from '@molecule/app-ai-models';
+export type { EffortLevel, EffortOption };
+export { defaultEffortForModel, effortOptionsForModel, nativeEffortName, } from '@molecule/app-ai-models';
+/**
+ * Conversation modes that carry their own effort level. Kept as a plain string
+ * union locally (mirrors the chat mode type); future modes extend this without
+ * changing the settings shape — `effortByMode` is keyed by mode id.
+ */
+export type EffortMode = 'plan' | 'execute';
+/**
+ * The parsed result of an `/effort` command:
+ *
+ * - `set` — apply the (still-unresolved) native value `arg`, optionally scoped
+ *   to a specific `mode` via `--plan` / `--execute` (unscoped = current mode).
+ *   Resolve `arg` against the target model's options with
+ *   {@link resolveEffortArg} — parsing is purely syntactic because the valid
+ *   values depend on which model the target mode runs.
+ * - `query` — show the status view (`/effort` or `/effort ?`).
+ * - `invalid` — unrecognized flags/arguments (the caller shows usage).
+ */
+export type EffortCommand = {
+    kind: 'set';
+    arg: string;
+    mode?: EffortMode;
+} | {
+    kind: 'query';
+    mode?: EffortMode;
+} | {
+    kind: 'invalid';
+    arg: string;
+};
+/**
+ * Parses an `/effort [--plan|--execute] [arg]` command. Purely syntactic — the
+ * caller resolves `arg` against the target mode's model via
+ * {@link resolveEffortArg}. Returns `null` when the input is not the command.
+ *
+ * @param input - The raw chat input.
+ * @returns The parsed {@link EffortCommand}, or `null`.
+ */
+export declare function parseEffortCommand(input: string): EffortCommand | null;
+/**
+ * Resolve a user-typed effort value against a model's selectable options.
+ *
+ * Matches the model's own native values case-insensitively (`xhigh`, `16K`, …)
+ * and returns the canonical value to persist. Returns `null` when the input
+ * doesn't name one of the model's levels.
+ *
+ * @param arg - The raw value the user typed.
+ * @param options - The target model's options (see `effortOptionsForModel`).
+ * @returns The native value to persist, or `null` when nothing matches.
+ */
+export declare function resolveEffortArg(arg: string, options: readonly EffortOption[]): EffortLevel | null;
+/**
+ * The catalog models that expose a *configurable* reasoning/thinking budget —
+ * i.e. those where the effort level maps onto a provider reasoning param. Models
+ * with no configurable budget still get the agent-loop budget applied by the
+ * backend, but these are the ones the `?` view highlights.
+ *
+ * @param models - The available models from the catalog.
+ * @returns The models supporting a configurable reasoning budget, in input order.
+ */
+export declare function modelsSupportingEffort(models: readonly AppModelDefinition[]): AppModelDefinition[];
+/**
+ * The effort levels the `/effort` command offers and accepts for a *specific*
+ * model — the model's own native values, ascending (e.g.
+ * `['low', 'high', 'xhigh', 'max']`). Empty for a fixed-reasoning model
+ * (`grok-code-fast-1`, the DeepSeek executors) or an unknown model, which
+ * expose no effort choice.
+ *
+ * @param model - The active model to read levels from, or `undefined`.
+ * @returns The model's effort levels in ascending order (empty when it has none).
+ */
+export declare function effortLevelsForModel(model: AppModelDefinition | undefined): readonly string[];
+//# sourceMappingURL=chat-effort-utilities.d.ts.map

package/dist/components/chat-effort-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-effort-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-effort-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE5F,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA;AACzC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAEhC;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAiBtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,YAAY,EAAE,GAC/B,WAAW,GAAG,IAAI,CAGpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GACpC,kBAAkB,EAAE,CAEtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,CAE7F"}

package/dist/components/chat-effort-utilities.js

@@ -0,0 +1,97 @@
+/**
+ * Pure helpers backing the `/effort` command and its status view.
+ *
+ * Effort is persisted PER MODE (`settings.effortByMode`, with the legacy single
+ * `settings.effortLevel` as fallback) as the model's OWN native value — there is
+ * no abstract scale. Users see and type the ACTIVE MODEL's own effort values
+ * (`xhigh` on Claude Opus 4.8, `medium` on Grok 4.3, `16K` thinking tokens on
+ * budget-configurable models …), which vary per model and therefore per mode:
+ * plan and execute run different models, so each mode carries its own value
+ * chosen from its own model's levels.
+ *
+ * Command shapes:
+ * - `/effort` or `/effort ?` — status for every mode.
+ * - `/effort <value>` — set the CURRENT mode's effort to a native value.
+ * - `/effort --plan <value>` / `/effort --execute <value>` — set a specific
+ *   mode's effort (mirrors `/model --plan` / `--execute`).
+ *
+ * Deterministic and side-effect free — unit testable without rendering or a
+ * backend. User-facing prose lives in the component via `t()`.
+ *
+ * @module
+ */
+export { defaultEffortForModel, effortOptionsForModel, nativeEffortName, } from '@molecule/app-ai-models';
+/**
+ * Parses an `/effort [--plan|--execute] [arg]` command. Purely syntactic — the
+ * caller resolves `arg` against the target mode's model via
+ * {@link resolveEffortArg}. Returns `null` when the input is not the command.
+ *
+ * @param input - The raw chat input.
+ * @returns The parsed {@link EffortCommand}, or `null`.
+ */
+export function parseEffortCommand(input) {
+    const match = input.trim().match(/^\/effort(?:\s+(.*))?$/i);
+    if (!match)
+        return null;
+    const tokens = (match[1] ?? '').trim().split(/\s+/).filter(Boolean);
+    let mode;
+    const rest = [];
+    for (const token of tokens) {
+        const lower = token.toLowerCase();
+        if (lower === '--plan')
+            mode = 'plan';
+        else if (lower === '--execute')
+            mode = 'execute';
+        else
+            rest.push(token);
+    }
+    if (rest.length === 0)
+        return { kind: 'query', mode };
+    if (rest.length > 1)
+        return { kind: 'invalid', arg: rest.join(' ') };
+    const arg = rest[0];
+    if (arg === '?')
+        return { kind: 'query', mode };
+    return { kind: 'set', arg, mode };
+}
+/**
+ * Resolve a user-typed effort value against a model's selectable options.
+ *
+ * Matches the model's own native values case-insensitively (`xhigh`, `16K`, …)
+ * and returns the canonical value to persist. Returns `null` when the input
+ * doesn't name one of the model's levels.
+ *
+ * @param arg - The raw value the user typed.
+ * @param options - The target model's options (see `effortOptionsForModel`).
+ * @returns The native value to persist, or `null` when nothing matches.
+ */
+export function resolveEffortArg(arg, options) {
+    const lower = arg.toLowerCase();
+    return options.find((o) => o.value.toLowerCase() === lower)?.value ?? null;
+}
+/**
+ * The catalog models that expose a *configurable* reasoning/thinking budget —
+ * i.e. those where the effort level maps onto a provider reasoning param. Models
+ * with no configurable budget still get the agent-loop budget applied by the
+ * backend, but these are the ones the `?` view highlights.
+ *
+ * @param models - The available models from the catalog.
+ * @returns The models supporting a configurable reasoning budget, in input order.
+ */
+export function modelsSupportingEffort(models) {
+    return models.filter((m) => m.supportsThinking && m.thinkingConfigurable);
+}
+/**
+ * The effort levels the `/effort` command offers and accepts for a *specific*
+ * model — the model's own native values, ascending (e.g.
+ * `['low', 'high', 'xhigh', 'max']`). Empty for a fixed-reasoning model
+ * (`grok-code-fast-1`, the DeepSeek executors) or an unknown model, which
+ * expose no effort choice.
+ *
+ * @param model - The active model to read levels from, or `undefined`.
+ * @returns The model's effort levels in ascending order (empty when it has none).
+ */
+export function effortLevelsForModel(model) {
+    return model?.supportedEffortLevels ?? [];
+}
+//# sourceMappingURL=chat-effort-utilities.js.map

package/dist/components/chat-effort-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-effort-utilities.js","sourceRoot":"","sources":["../../src/components/chat-effort-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAyBhC;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC3D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACnE,IAAI,IAA4B,CAAA;IAChC,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;QACjC,IAAI,KAAK,KAAK,QAAQ;YAAE,IAAI,GAAG,MAAM,CAAA;aAChC,IAAI,KAAK,KAAK,WAAW;YAAE,IAAI,GAAG,SAAS,CAAA;;YAC3C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACvB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACrD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAC/C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,OAAgC;IAEhC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAA;IAC/B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,EAAE,KAAK,IAAI,IAAI,CAAA;AAC5E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAqC;IAErC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,oBAAoB,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAqC;IACxE,OAAO,KAAK,EAAE,qBAAqB,IAAI,EAAE,CAAA;AAC3C,CAAC"}

package/dist/components/chat-help-utilities.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `/help` content model + plain-text generation.
+ *
+ * The help content is a concise high-level guide built from the structured
+ * {@link HELP_MODES} / {@link HELP_TIPS} constants below — never a
+ * hand-maintained string — so the rich {@link module:./HelpCard | HelpCard} and
+ * this plain-text fallback can never drift (both read the SAME constants). It
+ * explains the three conversation modes (discovery / plan / execute) and lists
+ * efficiency tips. It deliberately does NOT relist the slash commands — typing
+ * `/` opens the command menu, which does that better.
+ *
+ * `buildHelpText` is the i18n plain-text fallback (used as the system card's
+ * copy/screen-reader text and in any non-React consumer); `HelpCard` renders the
+ * same model as a card matching the `/settings` / `/skills` cards.
+ *
+ * All prose is i18n-ready via `t(key, values, { defaultValue })`.
+ *
+ * @module
+ */
+import type { IconName } from '@molecule/app-icons';
+import { type AgentIdentity } from '@molecule/app-react';
+/**
+ * The `/help` intro paragraph (i18n key + English default). Shared by the
+ * plain-text {@link buildHelpText} fallback and the rich `HelpCard`. May
+ * interpolate the `{{agentName}}` / `{{productName}}` tokens.
+ */
+export declare const HELP_INTRO: {
+    /** i18n key for the intro paragraph. */
+    readonly key: "ide.chat.help.intro";
+    /** English default for {@link HELP_INTRO.key}. */
+    readonly defaultValue: "{{agentName}} is {{productName}}'s AI coding agent. Describe what you want to build and it will scaffold, code, and iterate with you.";
+};
+/** A conversation mode shown in `/help`, with its icon-set glyph and i18n copy. */
+export interface HelpMode {
+    /** Mode id (also the `data-mol-id` suffix in the card). */
+    id: 'discovery' | 'plan' | 'execute';
+    /**
+     * Icon-set glyph name rendered beside the mode in the rich `HelpCard`
+     * (ignored by the plain-text {@link buildHelpText} fallback).
+     */
+    icon: IconName;
+    /** i18n key for the one-line mode description (may interpolate `{{agentName}}`). */
+    key: string;
+    /** English default for {@link HelpMode.key}. */
+    defaultValue: string;
+}
+/**
+ * The three conversation modes, in the order shown in `/help`. The single
+ * source of truth for both the plain-text fallback and the `HelpCard`.
+ */
+export declare const HELP_MODES: readonly HelpMode[];
+/** An efficiency tip shown in `/help`. */
+export interface HelpTip {
+    /** Tip id (also the `data-mol-id` suffix in the card). */
+    id: string;
+    /** i18n key for the tip (may interpolate `{{agentName}}`). */
+    key: string;
+    /**
+     * English default for {@link HelpTip.key}, INCLUDING the leading `•` bullet so
+     * it matches the values shipped in the companion locale bonds (and so the
+     * plain-text fallback stays byte-identical).
+     */
+    defaultValue: string;
+}
+/** The efficiency tips, in the order shown in `/help`. */
+export declare const HELP_TIPS: readonly HelpTip[];
+/** The keyboard-shortcuts footer line shown at the end of `/help`. */
+export declare const HELP_SHORTCUTS: {
+    /** i18n key for the shortcuts footer. */
+    readonly key: "ide.chat.help.shortcuts";
+    /** English default for {@link HELP_SHORTCUTS.key}. */
+    readonly defaultValue: "Press Cmd+/ (Ctrl+/ on Windows/Linux) to view all keyboard shortcuts.";
+};
+/**
+ * Builds the `/help` body — a concise high-level guide covering the conversation
+ * modes and efficiency tips. It deliberately does NOT relist the slash commands;
+ * typing `/` opens the command menu, which does that better. Generated from the
+ * shared {@link HELP_MODES} / {@link HELP_TIPS} constants so it stays in sync
+ * automatically — and never drifts from the rich `HelpCard`, which renders the
+ * same model.
+ *
+ * @param identity - Agent/product display identity used to interpolate the
+ *   `{{agentName}}` / `{{productName}}` tokens in the help copy (defaults to the
+ *   neutral {@link DEFAULT_AGENT_IDENTITY} so the shared package never hardcodes
+ *   a product name).
+ * @returns The fully-formatted, newline-delimited help text.
+ */
+export declare function buildHelpText(identity?: AgentIdentity): string;
+//# sourceMappingURL=chat-help-utilities.d.ts.map

package/dist/components/chat-help-utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-help-utilities.d.ts","sourceRoot":"","sources":["../../src/components/chat-help-utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,KAAK,aAAa,EAA0B,MAAM,qBAAqB,CAAA;AAEhF;;;;GAIG;AACH,eAAO,MAAM,UAAU;IACrB,wCAAwC;;IAExC,kDAAkD;;CAG1C,CAAA;AAEV,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,EAAE,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAA;IACd,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAA;IACX,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAsBhC,CAAA;AAEV,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAA;IACV,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAA;IACX;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,EAAE,SAAS,OAAO,EAgC9B,CAAA;AAEV,sEAAsE;AACtE,eAAO,MAAM,cAAc;IACzB,yCAAyC;;IAEzC,sDAAsD;;CAE9C,CAAA;AAEV;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,aAAsC,GAAG,MAAM,CA2BtF"}

package/dist/components/chat-help-utilities.js

@@ -0,0 +1,131 @@
+/**
+ * `/help` content model + plain-text generation.
+ *
+ * The help content is a concise high-level guide built from the structured
+ * {@link HELP_MODES} / {@link HELP_TIPS} constants below — never a
+ * hand-maintained string — so the rich {@link module:./HelpCard | HelpCard} and
+ * this plain-text fallback can never drift (both read the SAME constants). It
+ * explains the three conversation modes (discovery / plan / execute) and lists
+ * efficiency tips. It deliberately does NOT relist the slash commands — typing
+ * `/` opens the command menu, which does that better.
+ *
+ * `buildHelpText` is the i18n plain-text fallback (used as the system card's
+ * copy/screen-reader text and in any non-React consumer); `HelpCard` renders the
+ * same model as a card matching the `/settings` / `/skills` cards.
+ *
+ * All prose is i18n-ready via `t(key, values, { defaultValue })`.
+ *
+ * @module
+ */
+import { t } from '@molecule/app-i18n';
+import { DEFAULT_AGENT_IDENTITY } from '@molecule/app-react';
+/**
+ * The `/help` intro paragraph (i18n key + English default). Shared by the
+ * plain-text {@link buildHelpText} fallback and the rich `HelpCard`. May
+ * interpolate the `{{agentName}}` / `{{productName}}` tokens.
+ */
+export const HELP_INTRO = {
+    /** i18n key for the intro paragraph. */
+    key: 'ide.chat.help.intro',
+    /** English default for {@link HELP_INTRO.key}. */
+    defaultValue: "{{agentName}} is {{productName}}'s AI coding agent. Describe what you want to build and it will scaffold, code, and iterate with you.",
+};
+/**
+ * The three conversation modes, in the order shown in `/help`. The single
+ * source of truth for both the plain-text fallback and the `HelpCard`.
+ */
+export const HELP_MODES = [
+    {
+        id: 'discovery',
+        icon: 'question',
+        key: 'ide.chat.help.modeDiscovery',
+        defaultValue: 'Discovery — new conversations start here. {{agentName}} asks clarifying questions to nail down requirements before writing any code.',
+    },
+    {
+        id: 'plan',
+        icon: 'search',
+        key: 'ide.chat.help.modePlan',
+        defaultValue: 'Plan — {{agentName}} researches the codebase and proposes a plan WITHOUT editing files. Toggle with /plan. Best for big or risky changes.',
+    },
+    {
+        id: 'execute',
+        icon: 'pencil',
+        key: 'ide.chat.help.modeExecute',
+        defaultValue: 'Execute — the default working mode. {{agentName}} writes code, runs tools, and applies changes, then verifies them.',
+    },
+];
+/** The efficiency tips, in the order shown in `/help`. */
+export const HELP_TIPS = [
+    {
+        id: 'mention',
+        key: 'ide.chat.help.tipMention',
+        defaultValue: '• Type @filename to attach a project file as context (or drag & drop any file).',
+    },
+    {
+        id: 'slash',
+        key: 'ide.chat.help.tipSlash',
+        defaultValue: '• Type / to browse every command.',
+    },
+    {
+        id: 'plan',
+        key: 'ide.chat.help.tipPlan',
+        defaultValue: '• Use /plan to have {{agentName}} research before making changes.',
+    },
+    {
+        id: 'undo',
+        key: 'ide.chat.help.tipUndo',
+        defaultValue: "• Use /undo to revert the last AI turn's file changes if it goes off track.",
+    },
+    {
+        id: 'compact',
+        key: 'ide.chat.help.tipCompact',
+        defaultValue: '• Use /compact to compress context when the conversation gets long.',
+    },
+    {
+        id: 'specific',
+        key: 'ide.chat.help.tipSpecific',
+        defaultValue: '• Be specific — "Add a login page with email/password and Google OAuth" beats "add auth".',
+    },
+];
+/** The keyboard-shortcuts footer line shown at the end of `/help`. */
+export const HELP_SHORTCUTS = {
+    /** i18n key for the shortcuts footer. */
+    key: 'ide.chat.help.shortcuts',
+    /** English default for {@link HELP_SHORTCUTS.key}. */
+    defaultValue: 'Press Cmd+/ (Ctrl+/ on Windows/Linux) to view all keyboard shortcuts.',
+};
+/**
+ * Builds the `/help` body — a concise high-level guide covering the conversation
+ * modes and efficiency tips. It deliberately does NOT relist the slash commands;
+ * typing `/` opens the command menu, which does that better. Generated from the
+ * shared {@link HELP_MODES} / {@link HELP_TIPS} constants so it stays in sync
+ * automatically — and never drifts from the rich `HelpCard`, which renders the
+ * same model.
+ *
+ * @param identity - Agent/product display identity used to interpolate the
+ *   `{{agentName}}` / `{{productName}}` tokens in the help copy (defaults to the
+ *   neutral {@link DEFAULT_AGENT_IDENTITY} so the shared package never hardcodes
+ *   a product name).
+ * @returns The fully-formatted, newline-delimited help text.
+ */
+export function buildHelpText(identity = DEFAULT_AGENT_IDENTITY) {
+    const { agentName, productName } = identity;
+    const values = { agentName, productName };
+    const lines = [];
+    // ── Getting started ──
+    lines.push(t('ide.chat.help.introHeading', undefined, { defaultValue: '── Getting Started ──' }), t(HELP_INTRO.key, values, { defaultValue: HELP_INTRO.defaultValue }), '');
+    // ── Modes ──
+    lines.push(t('ide.chat.help.modesHeading', undefined, { defaultValue: '── Modes ──' }));
+    for (const helpMode of HELP_MODES) {
+        lines.push(t(helpMode.key, values, { defaultValue: helpMode.defaultValue }));
+    }
+    lines.push('');
+    // ── Efficiency tips ──
+    lines.push(t('ide.chat.help.tipsHeading', undefined, { defaultValue: '── Tips ──' }));
+    for (const tip of HELP_TIPS) {
+        lines.push(t(tip.key, values, { defaultValue: tip.defaultValue }));
+    }
+    lines.push('', t(HELP_SHORTCUTS.key, undefined, { defaultValue: HELP_SHORTCUTS.defaultValue }));
+    return lines.join('\n');
+}
+//# sourceMappingURL=chat-help-utilities.js.map

package/dist/components/chat-help-utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-help-utilities.js","sourceRoot":"","sources":["../../src/components/chat-help-utilities.ts"],"names":[],"mappings":"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"}