xtralab 0.11.0 → 0.12.0

package/src/git/notebookDiff.tsx

@@ -3,6 +3,7 @@ import * as React from 'react';
 import type * as nbformat from '@jupyterlab/nbformat';
 import { OutputAreaModel, SimplifiedOutputArea } from '@jupyterlab/outputarea';
 import { IRenderMimeRegistry, MimeModel } from '@jupyterlab/rendermime';
+import type { TranslationBundle } from '@jupyterlab/translation';
 import { MessageLoop } from '@lumino/messaging';
 import { Widget } from '@lumino/widgets';
 import { FileDiff } from '@pierre/diffs/react';
@@ -20,14 +21,14 @@ import { resolveDiffTheme } from './diffTheme';
  * style cell sections, headers, and the per-cell diff blocks hang off this
  * class.
  */
-export const NOTEBOOK_DIFF_CSS_CLASS = 'jp-xtralab-NotebookDiff';
+const NOTEBOOK_DIFF_CSS_CLASS = 'jp-xtralab-NotebookDiff';
 
 /**
  * Minimal slice of nbformat 4.x that the diff inspects. Fields we don't
  * read (attachments, e.g.) are intentionally not narrowed — we still pass
  * them around as part of the cell, but we never project them into the diff.
  */
-export interface INotebookCell {
+interface INotebookCell {
   cell_type: string;
   id?: string;
   source: string | string[];
@@ -37,7 +38,7 @@ export interface INotebookCell {
   attachments?: Record<string, unknown>;
 }
 
-export interface INotebookOutput {
+interface INotebookOutput {
   output_type: string;
   data?: Record<string, unknown>;
   text?: string | string[];
@@ -49,7 +50,7 @@ export interface INotebookOutput {
   metadata?: Record<string, unknown>;
 }
 
-export interface INotebook {
+interface INotebook {
   cells: INotebookCell[];
   metadata: Record<string, unknown>;
   nbformat: number;
@@ -63,7 +64,7 @@ export interface INotebook {
  * carry the same payload but live on separate union members so `Extract`
  * narrowing works on `kind` literals downstream.
  */
-export type NotebookCellDiff =
+type NotebookCellDiff =
   | {
       kind: 'modified';
       oldCell: INotebookCell;
@@ -116,7 +117,7 @@ export interface INotebookDiffResult {
  * look like a notebook (missing `cells` array). The caller falls back to a
  * raw text diff so a malformed file is still inspectable.
  */
-export function parseNotebook(text: string): INotebook | null {
+function parseNotebook(text: string): INotebook | null {
   if (text.length === 0) {
     return emptyNotebook();
   }
@@ -155,14 +156,14 @@ function emptyNotebook(): INotebook {
  * strings. Normalize to one string so equality checks and diffs see the
  * same shape regardless of how the writer chose to serialize it.
  */
-export function joinMultiline(value: string | string[] | undefined): string {
+function joinMultiline(value: string | string[] | undefined): string {
   if (value === undefined) {
     return '';
   }
   return Array.isArray(value) ? value.join('') : value;
 }
 
-export function cellSource(cell: INotebookCell): string {
+function cellSource(cell: INotebookCell): string {
   return joinMultiline(cell.source);
 }
 
@@ -173,7 +174,7 @@ export function cellSource(cell: INotebookCell): string {
  * to a `<mime-type>` placeholder so diffing image bytes doesn't drown the
  * panel in base64 noise.
  */
-export function canonicalOutputs(cell: INotebookCell): string {
+function canonicalOutputs(cell: INotebookCell): string {
   const outputs = cell.outputs ?? [];
   if (outputs.length === 0) {
     return '';
@@ -241,7 +242,7 @@ function stripAnsi(value: string): string {
  * An empty metadata object returns the empty string so freshly-added cells
  * that carry the default `{}` don't produce a `+{}` placeholder section.
  */
-export function canonicalMetadata(cell: INotebookCell): string {
+function canonicalMetadata(cell: INotebookCell): string {
   const md = cell.metadata ?? {};
   if (Object.keys(md).length === 0) {
     return '';
@@ -254,7 +255,7 @@ export function canonicalMetadata(cell: INotebookCell): string {
  * info, nbformat). We diff the bundle as a single block so the user sees
  * all environment-level changes in one place.
  */
-export function canonicalNotebookMetadata(notebook: INotebook): string {
+function canonicalNotebookMetadata(notebook: INotebook): string {
   return stableStringify({
     metadata: notebook.metadata,
     nbformat: notebook.nbformat,
@@ -266,11 +267,11 @@ function stableStringify(value: unknown): string {
   return JSON.stringify(value, sortKeysReplacer, 2);
 }
 
-function sortKeysReplacer(_key: string, value: unknown): unknown {
+function sortKeysReplacer(key: string, value: unknown): unknown {
   if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
     const sorted: Record<string, unknown> = {};
-    for (const key of Object.keys(value).sort()) {
-      sorted[key] = (value as Record<string, unknown>)[key];
+    for (const name of Object.keys(value).sort()) {
+      sorted[name] = (value as Record<string, unknown>)[name];
     }
     return sorted;
   }
@@ -284,7 +285,7 @@ function sortKeysReplacer(_key: string, value: unknown): unknown {
  * itself sees, so an "equal" verdict here implies all per-cell diff blocks
  * would be empty.
  */
-export function cellsAreEqual(a: INotebookCell, b: INotebookCell): boolean {
+function cellsAreEqual(a: INotebookCell, b: INotebookCell): boolean {
   return (
     a.cell_type === b.cell_type &&
     cellSource(a) === cellSource(b) &&
@@ -305,7 +306,7 @@ export function cellsAreEqual(a: INotebookCell, b: INotebookCell): boolean {
  * edits this is more readable than guessing alignment between unrelated
  * insertions and deletions.
  */
-export function alignNotebookCells(
+function alignNotebookCells(
   oldCells: INotebookCell[],
   newCells: INotebookCell[]
 ): NotebookCellDiff[] {
@@ -373,7 +374,7 @@ export function alignNotebookCells(
   return entries;
 }
 
-export interface IBuildNotebookDiffOptions {
+interface IBuildNotebookDiffOptions {
   oldText: string;
   newText: string;
 }
@@ -754,8 +755,9 @@ function OutputsSection(props: {
   entry: NotebookCellDiff;
   rendermime: IRenderMimeRegistry | null;
   placement: CellPlacement;
+  trans: TranslationBundle;
 }): React.ReactElement | null {
-  const { entry, rendermime, placement } = props;
+  const { entry, rendermime, placement, trans } = props;
   const oldCell = 'oldCell' in entry ? entry.oldCell : null;
   const newCell = 'newCell' in entry ? entry.newCell : null;
   const oldOutputs = oldCell?.outputs ?? [];
@@ -775,7 +777,7 @@ function OutputsSection(props: {
   if (rendermime === null) {
     return (
       <SideBySidePanes
-        label="Outputs"
+        label={trans.__('Outputs')}
         hasOld={showOld}
         hasNew={showNew}
         oldNode={
@@ -793,7 +795,7 @@ function OutputsSection(props: {
   }
   return (
     <SideBySidePanes
-      label="Outputs"
+      label={trans.__('Outputs')}
       hasOld={showOld}
       hasNew={showNew}
       oldNode={<OutputsPreview outputs={oldOutputs} rendermime={rendermime} />}
@@ -811,8 +813,9 @@ function MarkdownPreviewSection(props: {
   entry: NotebookCellDiff;
   rendermime: IRenderMimeRegistry | null;
   placement: CellPlacement;
+  trans: TranslationBundle;
 }): React.ReactElement | null {
-  const { entry, rendermime, placement } = props;
+  const { entry, rendermime, placement, trans } = props;
   const isMarkdown = referenceCellType(entry) === 'markdown';
   if (!isMarkdown || rendermime === null) {
     return null;
@@ -826,7 +829,7 @@ function MarkdownPreviewSection(props: {
   }
   return (
     <SideBySidePanes
-      label="Rendered"
+      label={trans.__('Rendered')}
       hasOld={showOld}
       hasNew={showNew}
       oldNode={<MarkdownPreview source={oldSource} rendermime={rendermime} />}
@@ -844,6 +847,10 @@ interface INotebookDiffViewProps {
    */
   pierreTheme: boolean;
   rendermime: IRenderMimeRegistry | null;
+  /**
+   * Translation bundle for user-facing strings.
+   */
+  trans: TranslationBundle;
 }
 
 /**
@@ -859,12 +866,12 @@ interface INotebookDiffViewProps {
 export function NotebookDiffView(
   props: INotebookDiffViewProps
 ): React.ReactElement {
-  const { diff, dark, pierreTheme, rendermime } = props;
+  const { diff, dark, pierreTheme, rendermime, trans } = props;
   const theme: DiffsThemeNames = resolveDiffTheme(dark, pierreTheme);
   const summary = React.useMemo(() => summarize(diff.cells), [diff.cells]);
   return (
     <div className={NOTEBOOK_DIFF_CSS_CLASS}>
-      <NotebookDiffHeader summary={summary} />
+      <NotebookDiffHeader summary={summary} trans={trans} />
       <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-grid`}>
         {diff.cells.map(entry => (
           <CellEntryRow
@@ -874,6 +881,7 @@ export function NotebookDiffView(
             theme={theme}
             dark={dark}
             rendermime={rendermime}
+            trans={trans}
           />
         ))}
       </div>
@@ -882,6 +890,7 @@ export function NotebookDiffView(
           metadata={diff.notebookMetadataDiff}
           theme={theme}
           dark={dark}
+          trans={trans}
         />
       ) : null}
     </div>
@@ -897,11 +906,11 @@ export function NotebookDiffView(
  * cell was inserted or removed relative to the other side.
  */
 function CellEntryRow(props: ICellDiffBlockProps): React.ReactElement {
-  const { entry } = props;
+  const { entry, trans } = props;
   if (entry.kind === 'added') {
     return (
       <>
-        <EmptyCellPlaceholder side="old" reason="added" />
+        <EmptyCellPlaceholder side="old" reason="added" trans={trans} />
         <CellDiffBlock {...props} placement="right" />
       </>
     );
@@ -910,7 +919,7 @@ function CellEntryRow(props: ICellDiffBlockProps): React.ReactElement {
     return (
       <>
         <CellDiffBlock {...props} placement="left" />
-        <EmptyCellPlaceholder side="new" reason="removed" />
+        <EmptyCellPlaceholder side="new" reason="removed" trans={trans} />
       </>
     );
   }
@@ -920,9 +929,13 @@ function CellEntryRow(props: ICellDiffBlockProps): React.ReactElement {
 function EmptyCellPlaceholder(props: {
   side: 'old' | 'new';
   reason: 'added' | 'removed';
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { side, reason } = props;
-  const label = reason === 'added' ? 'cell added on the right' : 'cell removed';
+  const { side, reason, trans } = props;
+  const label =
+    reason === 'added'
+      ? trans.__('cell added on the right')
+      : trans.__('cell removed');
   return (
     <div
       className={`${NOTEBOOK_DIFF_CSS_CLASS}-empty`}
@@ -930,7 +943,9 @@ function EmptyCellPlaceholder(props: {
       aria-label={label}
     >
       <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-emptyLabel`}>
-        {reason === 'added' ? '— no cell —' : '— cell removed —'}
+        {reason === 'added'
+          ? trans.__('— no cell —')
+          : trans.__('— cell removed —')}
       </span>
     </div>
   );
@@ -958,31 +973,32 @@ function summarize(cells: NotebookCellDiff[]): INotebookDiffSummary {
 
 function NotebookDiffHeader(props: {
   summary: INotebookDiffSummary;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { summary } = props;
+  const { summary, trans } = props;
   const total =
     summary.added + summary.removed + summary.modified + summary.unchanged;
   return (
     <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-header`}>
       <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-headerCount`}>
-        {total} cell{total === 1 ? '' : 's'}
+        {trans._n('%1 cell', '%1 cells', total)}
       </span>
       {summary.modified > 0 ? (
         <span
           className={`${NOTEBOOK_DIFF_CSS_CLASS}-stat`}
           data-kind="modified"
         >
-          {summary.modified} modified
+          {trans.__('%1 modified', summary.modified)}
         </span>
       ) : null}
       {summary.added > 0 ? (
         <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-stat`} data-kind="added">
-          {summary.added} added
+          {trans.__('%1 added', summary.added)}
         </span>
       ) : null}
       {summary.removed > 0 ? (
         <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-stat`} data-kind="removed">
-          {summary.removed} removed
+          {trans.__('%1 removed', summary.removed)}
         </span>
       ) : null}
       {summary.unchanged > 0 ? (
@@ -990,7 +1006,7 @@ function NotebookDiffHeader(props: {
           className={`${NOTEBOOK_DIFF_CSS_CLASS}-stat`}
           data-kind="unchanged"
         >
-          {summary.unchanged} unchanged
+          {trans.__('%1 unchanged', summary.unchanged)}
         </span>
       ) : null}
     </div>
@@ -1013,6 +1029,7 @@ interface ICellDiffBlockProps {
   theme: DiffsThemeNames;
   dark: boolean;
   rendermime: IRenderMimeRegistry | null;
+  trans: TranslationBundle;
 }
 
 /**
@@ -1034,7 +1051,7 @@ interface IPlacedCellDiffBlockProps extends ICellDiffBlockProps {
 }
 
 function CellDiffBlock(props: IPlacedCellDiffBlockProps): React.ReactElement {
-  const { entry, language, theme, dark, rendermime, placement } = props;
+  const { entry, language, theme, dark, rendermime, placement, trans } = props;
   // Unchanged cells start collapsed — the user opted out of seeing those
   // sections by virtue of them being unchanged. A toggle lets them peek if
   // they want.
@@ -1081,21 +1098,25 @@ function CellDiffBlock(props: IPlacedCellDiffBlockProps): React.ReactElement {
           className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellBadge`}
           data-kind={entry.kind}
         >
-          {kindBadge(entry.kind)}
+          {kindBadge(entry.kind, trans)}
         </span>
         <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellLabel`}>
           {indexLabel} · {cellType}
         </span>
         {entry.kind === 'unchanged' ? (
           <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellHint`}>
-            unchanged
+            {trans.__('unchanged')}
           </span>
         ) : null}
       </header>
       {!collapsed ? (
         <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellBody`}>
           {entry.kind === 'unchanged' ? (
-            <UnchangedCellBody entry={entry} rendermime={rendermime} />
+            <UnchangedCellBody
+              entry={entry}
+              rendermime={rendermime}
+              trans={trans}
+            />
           ) : (
             <>
               {subdiffs.map(sub => (
@@ -1106,18 +1127,21 @@ function CellDiffBlock(props: IPlacedCellDiffBlockProps): React.ReactElement {
                   theme={theme}
                   dark={dark}
                   placement={placement}
+                  trans={trans}
                 />
               ))}
               <MarkdownPreviewSection
                 entry={entry}
                 rendermime={rendermime}
                 placement={placement}
+                trans={trans}
               />
               {showOutputs ? (
                 <OutputsSection
                   entry={entry}
                   rendermime={rendermime}
                   placement={placement}
+                  trans={trans}
                 />
               ) : null}
               {subdiffs.length === 0 &&
@@ -1127,7 +1151,7 @@ function CellDiffBlock(props: IPlacedCellDiffBlockProps): React.ReactElement {
                   ('newCell' in entry && entry.newCell.outputs?.length))
               ) ? (
                 <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellEmpty`}>
-                  No content differences detected.
+                  {trans.__('No content differences detected.')}
                 </div>
               ) : null}
             </>
@@ -1144,8 +1168,9 @@ function CellSubDiff(props: {
   theme: DiffsThemeNames;
   dark: boolean;
   placement: CellPlacement;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { kind, metadata, theme, dark, placement } = props;
+  const { kind, metadata, theme, dark, placement, trans } = props;
   // For modified / unchanged cells the diff spans both outer columns, and
   // split mode lets it visually align with the outer old | new lanes. For
   // added / removed cells the diff sits inside a single outer column, so
@@ -1156,7 +1181,7 @@ function CellSubDiff(props: {
   return (
     <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-subdiff`} data-section={kind}>
       <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-subdiffLabel`}>
-        {subdiffLabel(kind)}
+        {subdiffLabel(kind, trans)}
       </div>
       <FileDiff
         fileDiff={metadata}
@@ -1175,8 +1200,9 @@ function NotebookMetadataBlock(props: {
   metadata: FileDiffMetadata;
   theme: DiffsThemeNames;
   dark: boolean;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { metadata, theme, dark } = props;
+  const { metadata, theme, dark, trans } = props;
   return (
     <section
       className={`${NOTEBOOK_DIFF_CSS_CLASS}-cell`}
@@ -1185,17 +1211,17 @@ function NotebookMetadataBlock(props: {
     >
       <header
         className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellHeader`}
-        aria-label="Notebook metadata"
+        aria-label={trans.__('Notebook metadata')}
       >
         <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellChevron`}>▾</span>
         <span
           className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellBadge`}
           data-kind="modified"
         >
-          M
+          {trans.__('M')}
         </span>
         <span className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellLabel`}>
-          Notebook metadata
+          {trans.__('Notebook metadata')}
         </span>
       </header>
       <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-cellBody`}>
@@ -1205,6 +1231,7 @@ function NotebookMetadataBlock(props: {
           theme={theme}
           dark={dark}
           placement="full"
+          trans={trans}
         />
       </div>
     </section>
@@ -1222,8 +1249,9 @@ function NotebookMetadataBlock(props: {
 function UnchangedCellBody(props: {
   entry: Extract<NotebookCellDiff, { kind: 'unchanged' }>;
   rendermime: IRenderMimeRegistry | null;
+  trans: TranslationBundle;
 }): React.ReactElement {
-  const { entry, rendermime } = props;
+  const { entry, rendermime, trans } = props;
   const cell = entry.newCell;
   const source = cellSource(cell);
   const isMarkdown = cell.cell_type === 'markdown';
@@ -1237,13 +1265,13 @@ function UnchangedCellBody(props: {
         </div>
       ) : (
         <pre className={`${NOTEBOOK_DIFF_CSS_CLASS}-unchangedSource`}>
-          {source.length > 0 ? source : '(empty cell)'}
+          {source.length > 0 ? source : trans.__('(empty cell)')}
         </pre>
       )}
       {hasOutputs && rendermime !== null ? (
         <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-unchangedOutputs`}>
           <div className={`${NOTEBOOK_DIFF_CSS_CLASS}-subdiffLabel`}>
-            Outputs
+            {trans.__('Outputs')}
           </div>
           <OutputsPreview outputs={outputs} rendermime={rendermime} />
         </div>
@@ -1275,24 +1303,30 @@ function cellIndexLabel(entry: NotebookCellDiff): string {
   return `Cell ${entry.oldIndex + 1} → ${entry.newIndex + 1}`;
 }
 
-function kindBadge(kind: NotebookCellDiff['kind']): string {
+function kindBadge(
+  kind: NotebookCellDiff['kind'],
+  trans: TranslationBundle
+): string {
   switch (kind) {
     case 'added':
-      return 'A';
+      return trans.__('A');
     case 'removed':
-      return 'D';
+      return trans.__('D');
     case 'modified':
-      return 'M';
+      return trans.__('M');
     case 'unchanged':
       return '·';
   }
 }
 
-function subdiffLabel(kind: 'source' | 'metadata'): string {
+function subdiffLabel(
+  kind: 'source' | 'metadata',
+  trans: TranslationBundle
+): string {
   switch (kind) {
     case 'source':
-      return 'Source';
+      return trans.__('Source');
     case 'metadata':
-      return 'Metadata';
+      return trans.__('Metadata');
   }
 }

package/src/git/tokens.ts

@@ -19,7 +19,9 @@ export interface IGitStatusFile {
   is_binary: boolean | null;
 }
 
-/** Response shape of `POST /git/<path>/status`. */
+/**
+ * Response shape of `POST /git/<path>/status`.
+ */
 export interface IGitStatusResult {
   code: number;
   branch: string | null;
@@ -61,7 +63,7 @@ export interface IGitContentResult {
  * changes on top of an already-staged version. The panel models that as two
  * separate entries, one per group.
  */
-export type FileChangeGroup = 'staged' | 'unstaged';
+type FileChangeGroup = 'staged' | 'unstaged';
 
 /**
  * The user-facing status of a file change. Drives the single-letter badge

package/src/highlight/index.ts

@@ -5,6 +5,7 @@ import {
 import { ICommandPalette } from '@jupyterlab/apputils';
 import { CodeMirrorEditor } from '@jupyterlab/codemirror';
 import { IDocumentManager } from '@jupyterlab/docmanager';
+import { FileEditor } from '@jupyterlab/fileeditor';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { StateEffect, StateField } from '@codemirror/state';
 import { Decoration, DecorationSet, EditorView } from '@codemirror/view';
@@ -20,7 +21,9 @@ const PLUGIN_ID = 'xtralab:highlight';
 const HIGHLIGHT_LINES_COMMAND = 'xtralab:highlight-lines';
 const CLEAR_HIGHLIGHTS_COMMAND = 'xtralab:clear-highlights';
 
-/** CodeMirror line-decoration class; styled in style/highlight.css. */
+/**
+ * CodeMirror line-decoration class; styled in style/highlight.css.
+ */
 const HIGHLIGHT_LINE_CLASS = 'jp-xtralab-highlightLine';
 
 /**
@@ -66,15 +69,16 @@ const highlightField = StateField.define<DecorationSet>({
 });
 
 /**
- * Return the CodeMirror view backing a widget's editor, or `null` when the
- * widget is not a CodeMirror-based text editor (a notebook, a terminal, the
- * settings editor, …). Duck-typed on `content.editor` so the plugin does not
- * depend on `@jupyterlab/fileeditor`.
+ * Return the CodeMirror view backing a widget's file editor, or `null` when
+ * the widget is not a CodeMirror-based text editor (a notebook, a terminal,
+ * the settings editor, …).
  */
 function viewForWidget(widget: Widget | null): EditorView | null {
-  const editor = (widget as { content?: { editor?: unknown } } | null)?.content
-    ?.editor;
-  return editor instanceof CodeMirrorEditor ? editor.editor : null;
+  const content = (widget as { content?: unknown } | null)?.content;
+  return content instanceof FileEditor &&
+    content.editor instanceof CodeMirrorEditor
+    ? content.editor.editor
+    : null;
 }
 
 /**

package/src/index.ts

@@ -1,6 +1,7 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 
 import agentSessionsPlugin from './agentSessions';
+import askAgentPlugin from './askAgent';
 import commandBarPlugin from './commandBar';
 import fileBrowserPlugin from './fileBrowser';
 import fileTypeIconsPlugin from './fileTypeIcons';
@@ -30,6 +31,7 @@ import walkthroughPlugin from './walkthrough';
  */
 const plugins: JupyterFrontEndPlugin<unknown>[] = [
   agentSessionsPlugin,
+  askAgentPlugin,
   commandBarPlugin,
   editorBreadcrumbsPlugin,
   editorIndentPlugin,

package/src/launcher/agents.ts

@@ -63,7 +63,12 @@ export interface IAgentSettings {
    * palette. Defaults to true.
    */
   enabled?: boolean;
-  /** See `IAgent.requireAvailable`. */
+  /**
+   * See `IAgent.requireAvailable`. Defaults to true for a built-in agent that
+   * still uses its shipped command, and to false once you override the
+   * `command` (a user-chosen command — often a shell alias — is trusted and
+   * always shown). Set it explicitly to force the check on or off.
+   */
   requireAvailable?: boolean;
   /**
    * See `IAgent.promptArgs`. Pass an empty array to mark the agent as
@@ -80,10 +85,9 @@ export interface IAgentSettings {
  * in `jupyter-ai-contrib/jupyter-ai-acp-client` (which is also where their
  * icons come from), but use the bare CLI names a user would type in a
  * terminal rather than the ACP wrapper binaries that project spawns.
- * Antigravity (Google's agent-first IDE/CLI, `agy`) takes the Google slot —
- * Gemini CLI was dropped because Google is sunsetting it for consumer
- * accounts on 2026-06-18. Anything not on the user's `$PATH` is filtered
- * out at activation time, so the wider list is harmless.
+ * Antigravity (Google's agent-first IDE/CLI, `agy`) is the Google agent.
+ * Anything not on the user's `$PATH` is filtered out at activation time, so
+ * the wider list is harmless.
  */
 const DEFAULTS: IAgent[] = [
   {
@@ -215,6 +219,11 @@ function resolveIcon(id: string, iconSvg: string | undefined): LabIcon {
  * their built-in fields unless explicitly overridden; user-only entries are
  * appended. `enabled: false` filters an entry out of the result entirely
  * (so callers don't need to check the flag again).
+ *
+ * Overriding a built-in agent's `command` also turns its `requireAvailable`
+ * off, so the card survives the launcher's `which`-based availability filter
+ * even when the new command is a shell alias the server can't resolve. See the
+ * built-in branch below for the rationale.
  */
 export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
   const overrideById = new Map(overrides.map(entry => [entry.id, entry]));
@@ -230,16 +239,31 @@ export function mergeAgents(overrides: IAgentSettings[]): IAgent[] {
     if (override.enabled === false) {
       continue;
     }
+    const command = override.command ?? base.command;
     merged.push({
       id: base.id,
       label: override.label ?? base.label,
       caption: override.caption ?? base.caption,
-      command: override.command ?? base.command,
+      command,
       icon: override.iconSvg
         ? resolveIcon(base.id, override.iconSvg)
         : base.icon,
       rank: override.rank ?? base.rank,
-      requireAvailable: override.requireAvailable ?? base.requireAvailable,
+      // The availability filter exists to prune xtralab's *built-in* command
+      // from the launcher when it isn't installed. Once the user points the
+      // agent at their own command — e.g. the `ccm` alias wrapping `claude
+      // --effort=max …` — the server's `shutil.which` probe can't see it
+      // (aliases and shell functions only exist inside an interactive shell),
+      // so keeping the check on would wrongly hide the card. We therefore only
+      // require availability while the command is still xtralab's default; a
+      // user-chosen command is trusted and always shown. An explicit
+      // `requireAvailable` still applies to the unchanged default command, so a
+      // user can alias `claude` itself and set `requireAvailable: false` (or
+      // force the check back on).
+      requireAvailable:
+        command === base.command
+          ? (override.requireAvailable ?? base.requireAvailable)
+          : false,
       // `null` is the explicit way to opt out of an agent's default prompt
       // support; an absent key keeps the default. `undefined` from `??` is
       // pruned below.