@aion0/forge 0.10.12 → 0.10.18

package/RELEASE_NOTES.md

@@ -1,8 +1,8 @@
-# Forge v0.10.12
+# Forge v0.10.18
 
 Released: 2026-05-30
 
-## Changes since v0.10.11
+## Changes since v0.10.17
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.11...v0.10.12
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.17...v0.10.18

package/app/api/public-info/[resource]/route.ts

@@ -0,0 +1,40 @@
+/**
+ * GET /api/public-info/<resource>?refresh=1
+ *
+ * Server-side proxy + cache for files under the public-info repo. UI
+ * never hits GitHub directly — avoids CORS / rate-limit headaches and
+ * gives us a single cache shared across all browser tabs.
+ *
+ * Supported resources (extend by adding to RESOURCE_MAP):
+ *   - `models` → `models/registry.json`
+ *
+ * The UI passes the short name (`models`), this route translates to the
+ * actual path under the repo and pairs it with the right fallback.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { fetchPublicInfo } from '@/lib/public-info/fetch';
+import { KNOWN_MODELS_FALLBACK } from '@/lib/agents/known-models';
+
+interface ResourceSpec {
+  path: string;
+  fallback: unknown;
+}
+
+const RESOURCE_MAP: Record<string, ResourceSpec> = {
+  models: { path: 'models/registry.json', fallback: KNOWN_MODELS_FALLBACK },
+};
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ resource: string }> },
+): Promise<NextResponse> {
+  const { resource } = await params;
+  const spec = RESOURCE_MAP[resource];
+  if (!spec) {
+    return NextResponse.json({ error: `unknown resource: ${resource}` }, { status: 404 });
+  }
+  const forceRefresh = req.nextUrl.searchParams.get('refresh') === '1';
+  const data = await fetchPublicInfo(spec.path, spec.fallback, { forceRefresh });
+  return NextResponse.json(data);
+}

package/components/ProjectDetail.tsx

@@ -1678,7 +1678,7 @@ function AgentTerminalButton({ projectPath, projectName }: { projectPath: string
         currentSessionId,
       });
     } catch {
-      openTerminal(a.id);
+      openTerminal(a.id, false);
     }
   };
 

package/components/SettingsModal.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { FolderPicker } from './FolderPicker';
+import { useModelsRegistry, pickerOptions } from '@/lib/public-info/use-models-registry';
 
 function SecretInput({ value, onChange, placeholder, className }: {
   value: string;
@@ -917,6 +918,7 @@ function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete, isApi: isApiProp
   onUpdate: (cfg: any) => void; onDelete: () => void;
   isApi?: boolean;
 }) {
+  const { registry: modelsRegistry } = useModelsRegistry();
   const [expanded, setExpanded] = useState(false);
   const [testing, setTesting] = useState(false);
   const [testResult, setTestResult] = useState<{ ok: boolean; message?: string; error?: string; duration_ms?: number } | null>(null);
@@ -975,20 +977,23 @@ function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete, isApi: isApiProp
               <label className="text-[8px] text-[var(--text-secondary)]">Model</label>
               <input value={cfg.model || ''} onChange={e => onUpdate({ ...cfg, model: e.target.value })}
                 list={`profile-model-${id}`} className={inputClass} />
-              {(cfg.cliType === 'claude-code' || (!cfg.cliType && !cfg.base && !isApi)) && (
-                <datalist id={`profile-model-${id}`}>
-                  <option value="claude-opus-4-6" />
-                  <option value="claude-sonnet-4-6" />
-                  <option value="claude-haiku-4-5-20251001" />
-                </datalist>
-              )}
-              {(cfg.cliType === 'codex' || cfg.base === 'codex') && (
-                <datalist id={`profile-model-${id}`}>
-                  <option value="codex-mini" />
-                  <option value="o4-mini" />
-                  <option value="gpt-4o" />
-                </datalist>
-              )}
+              {/* Datalist sourced from forge-public-info registry — adding a new
+                  model id over there shows up here within 24h, no forge release.
+                  API profiles look up by provider; CLI profiles look up by cliType. */}
+              <datalist id={`profile-model-${id}`}>
+                {(() => {
+                  const models = isApi
+                    ? modelsRegistry.providers?.[cfg.provider || 'anthropic']?.models
+                    : modelsRegistry.agents[
+                        cfg.cliType === 'codex' || cfg.base === 'codex' ? 'codex'
+                        : cfg.cliType === 'aider' || cfg.base === 'aider' ? 'aider'
+                        : 'claude-code'
+                      ]?.models;
+                  return (models || []).map(m => (
+                    <option key={m.id} value={m.id} />
+                  ));
+                })()}
+              </datalist>
             </div>
           </div>
           {isApi ? (
@@ -1127,6 +1132,7 @@ function AddProfileForm({ type, baseAgents, onAdd }: {
   baseAgents: AgentEntry[];
   onAdd: (id: string, cfg: any) => void;
 }) {
+  const { registry: modelsRegistry } = useModelsRegistry();
   const [open, setOpen] = useState(false);
   const [id, setId] = useState('');
   const [name, setName] = useState('');
@@ -1228,22 +1234,17 @@ function AddProfileForm({ type, baseAgents, onAdd }: {
           <div className="flex-1">
             <label className="text-[8px] text-[var(--text-secondary)]">Model</label>
             <input value={model} onChange={e => setModel(e.target.value)}
-              placeholder={base === 'claude' ? 'claude-sonnet-4-6' : base === 'codex' ? 'codex-mini' : ''}
+              placeholder={
+                base === 'claude' ? modelsRegistry.agents['claude-code']?.default || ''
+                : base === 'codex' ? modelsRegistry.agents['codex']?.default || ''
+                : ''
+              }
               list={`model-list-${base}`} className={inputClass} />
-            {base === 'claude' && (
-              <datalist id="model-list-claude">
-                <option value="claude-opus-4-6" />
-                <option value="claude-sonnet-4-6" />
-                <option value="claude-haiku-4-5-20251001" />
-              </datalist>
-            )}
-            {base === 'codex' && (
-              <datalist id="model-list-codex">
-                <option value="codex-mini" />
-                <option value="o4-mini" />
-                <option value="gpt-4o" />
-              </datalist>
-            )}
+            <datalist id={`model-list-${base}`}>
+              {(modelsRegistry.agents[base === 'claude' ? 'claude-code' : base]?.models || []).map(m => (
+                <option key={m.id} value={m.id} />
+              ))}
+            </datalist>
           </div>
         </div>
         <div>
@@ -1275,7 +1276,14 @@ function AddProfileForm({ type, baseAgents, onAdd }: {
             </div>
             <div className="flex-1">
               <label className="text-[8px] text-[var(--text-secondary)]">Model</label>
-              <input value={model} onChange={e => setModel(e.target.value)} placeholder="claude-sonnet-4-6" className={inputClass} />
+              <input value={model} onChange={e => setModel(e.target.value)}
+                placeholder={modelsRegistry.providers?.[provider]?.default || ''}
+                list={`api-model-list-${provider}`} className={inputClass} />
+              <datalist id={`api-model-list-${provider}`}>
+                {(modelsRegistry.providers?.[provider]?.models || []).map(m => (
+                  <option key={m.id} value={m.id} />
+                ))}
+              </datalist>
             </div>
           </div>
           <div>
@@ -1314,6 +1322,7 @@ function AddProfileForm({ type, baseAgents, onAdd }: {
 }
 
 function AgentsSection({ settings, setSettings }: { settings: any; setSettings: (s: any) => void }) {
+  const { registry: modelsRegistry } = useModelsRegistry();
   const [agents, setAgents] = useState<AgentEntry[]>([]);
   const [loading, setLoading] = useState(true);
   const [expandedAgent, setExpandedAgent] = useState<string | null>(null);
@@ -1649,9 +1658,9 @@ function AgentsSection({ settings, setSettings }: { settings: any; setSettings:
                       <span className="text-[8px] text-[var(--text-secondary)]">Presets:</span>
                       {((() => {
                         const ct = (settings.agents?.[a.id] as any)?.cliType || (a.id === 'claude' ? 'claude-code' : a.id === 'codex' ? 'codex' : a.id === 'aider' ? 'aider' : 'generic');
-                        if (ct === 'claude-code') return ['default', 'sonnet', 'opus', 'haiku', 'claude-sonnet-4-6', 'claude-opus-4-6', 'claude-haiku-4-5-20251001'];
-                        if (ct === 'codex') return ['default', 'o3-mini', 'o4-mini', 'gpt-4.1'];
-                        return ['default'];
+                        // Models pulled from forge-public-info repo (lib/public-info/fetch.ts).
+                        // Add new IDs there and they show up here within 24h with no forge release.
+                        return pickerOptions(modelsRegistry, ct);
                       })()).map(preset => (
                         <button
                           key={preset}

package/components/WebTerminal.tsx

@@ -398,9 +398,11 @@ const WebTerminal = forwardRef<WebTerminalHandle, WebTerminalProps>(function Web
         agentSkipFlag = agentConfig?.skipPermissionsFlag || '';
       } catch {}
 
-      // Resume flag: explicit sessionId > fixedSession > -c (only for session-capable agents)
+      // Resume flag: explicit sessionId > fixedSession > -c (only for session-capable agents).
+      // resumeMode === false means the user explicitly chose "New Session" — never inject
+      // a fixedSession then, or "new" silently resumes the current one.
       let resumeFlag = '';
-      if (supportsSession) {
+      if (supportsSession && resumeMode !== false) {
         if (sessionId) resumeFlag = ` --resume ${sessionId}`;
         else if (resumeMode) resumeFlag = ' -c';
         // Override with fixedSession if no explicit sessionId
@@ -987,9 +989,12 @@ const WebTerminal = forwardRef<WebTerminalHandle, WebTerminalProps>(function Web
                                         currentSessionId,
                                       });
                                     } catch {
-                                      // Fallback: open directly without picker
+                                      // Fallback: open directly without picker.
+                                      // resumeMode:false so this fresh-open path skips the
+                                      // fixedSession resume branch downstream (else "open"
+                                      // silently resumes the current session).
                                       window.dispatchEvent(new CustomEvent('forge:open-terminal', {
-                                        detail: { projectPath: p.path, projectName: p.name, agentId: a.id },
+                                        detail: { projectPath: p.path, projectName: p.name, agentId: a.id, resumeMode: false },
                                       }));
                                     }
                                   }}
@@ -1068,7 +1073,10 @@ const WebTerminal = forwardRef<WebTerminalHandle, WebTerminalProps>(function Web
           onSelect={(sel) => {
             const info = vibePickerInfo;
             setVibePickerInfo(null);
-            const detail: any = { projectPath: info.projectPath, projectName: info.projectName, agentId: info.agentId, profileEnv: info.profileEnv };
+            // resumeMode must be LITERAL false for "new" — the downstream guard
+            // is `resumeMode !== false`, so leaving it undefined lets fixedSession
+            // get injected and "New session" silently resumes the current one.
+            const detail: any = { projectPath: info.projectPath, projectName: info.projectName, agentId: info.agentId, profileEnv: info.profileEnv, resumeMode: false };
             if (sel.mode !== 'new') { detail.resumeMode = true; detail.sessionId = sel.sessionId; }
             window.dispatchEvent(new CustomEvent('forge:open-terminal', { detail }));
           }}

package/components/WorkspaceView.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback, useMemo, useRef, forwardRef, useImperativeHandle, lazy, Suspense } from 'react';
 import { TerminalSessionPickerLazy, fetchAgentSessions, type PickerSelection } from './TerminalLauncher';
+import { useModelsRegistry } from '@/lib/public-info/use-models-registry';
 import {
   ReactFlow, Background, Controls, Handle, Position, useReactFlow, ReactFlowProvider,
   type Node, type NodeProps, MarkerType, type NodeChange,
@@ -715,6 +716,7 @@ function AgentConfigModal({ initial, mode, existingAgents, projectPath, onConfir
   onConfirm: (cfg: Omit<AgentConfig, 'id'>) => void;
   onCancel: () => void;
 }) {
+  const { registry: modelsRegistry } = useModelsRegistry();
   const [label, setLabel] = useState(initial.label || '');
   const [icon, setIcon] = useState(initial.icon || '🤖');
   const [role, setRole] = useState(initial.role || '');
@@ -1160,9 +1162,9 @@ function AgentConfigModal({ initial, mode, existingAgents, projectPath, onConfir
                   list="workspace-model-list"
                   className="text-xs bg-[#161b22] border border-[#30363d] rounded px-2 py-1 text-white focus:outline-none focus:border-[#58a6ff] font-mono" />
                 <datalist id="workspace-model-list">
-                  <option value="claude-sonnet-4-6" />
-                  <option value="claude-opus-4-6" />
-                  <option value="claude-haiku-4-5-20251001" />
+                  {(modelsRegistry.agents['claude-code']?.models || []).map(m => (
+                    <option key={m.id} value={m.id} />
+                  ))}
                 </datalist>
               </div>
             );

package/lib/agents/index.ts

@@ -280,7 +280,12 @@ export function resolveTerminalLaunch(agentId?: string): TerminalLaunchInfo {
   }
 
   return {
-    cliCmd: cli.cmd,
+    // Prefer the user-configured absolute binary path over the bare command
+    // name. A bare `claude` resolves via the tmux pane's PATH — non-login shell
+    // + forge-server's inherited PATH can pick a different/older install than
+    // the user's interactive shell, and an old claude crashes resuming a
+    // session a newer claude wrote. An absolute path bypasses PATH entirely.
+    cliCmd: agentCfg.path || cli.cmd,
     cliType,
     supportsSession: cli.session,
     resumeFlag: agentCfg.resumeFlag || cli.resume,

package/lib/agents/known-models.ts

@@ -0,0 +1,75 @@
+/**
+ * Built-in fallback model list. Forge prefers the public-info repo's
+ * registry (see `lib/public-info/fetch.ts`), but falls back to this
+ * when the network is unreachable, the file is malformed, or the
+ * user is on first-run before the cache is populated.
+ *
+ * Keep this list reasonably current — if the registry is permanently
+ * unreachable, this is what users see. New models in the wild should
+ * land in the public-info repo first (no code change required), and
+ * trickle into this fallback whenever the next forge release happens.
+ */
+
+import type { ModelsRegistry } from '../public-info/types';
+
+export const KNOWN_MODELS_FALLBACK: ModelsRegistry = {
+  version: 1,
+  updatedAt: '2026-05-30',
+  note: 'Bundled fallback — actual current list lives in forge-public-info/models/registry.json',
+  agents: {
+    'claude-code': {
+      displayName: 'Claude Code',
+      default: 'claude-sonnet-4-6',
+      aliases: [
+        { id: 'default', label: 'default (CLI decides)' },
+        { id: 'sonnet',  label: 'sonnet (alias)' },
+        { id: 'opus',    label: 'opus (alias)' },
+        { id: 'haiku',   label: 'haiku (alias)' },
+      ],
+      models: [
+        { id: 'claude-opus-4-8',           label: 'Opus 4.8',   tier: 'premium'  },
+        { id: 'claude-sonnet-4-6',         label: 'Sonnet 4.6', tier: 'standard', default: true },
+        { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5',  tier: 'fast'     },
+      ],
+    },
+    codex: {
+      displayName: 'OpenAI Codex',
+      default: 'o4-mini',
+      aliases: [{ id: 'default', label: 'default (CLI decides)' }],
+      models: [
+        { id: 'o4-mini', label: 'o4-mini', tier: 'fast',     default: true },
+        { id: 'o3-mini', label: 'o3-mini', tier: 'fast'                    },
+        { id: 'gpt-4.1', label: 'GPT-4.1', tier: 'standard'                },
+      ],
+    },
+    aider: {
+      displayName: 'Aider',
+      default: 'default',
+      aliases: [{ id: 'default', label: 'default (CLI decides)' }],
+      models: [],
+    },
+  },
+  providers: {
+    anthropic: {
+      displayName: 'Anthropic API',
+      default: 'claude-sonnet-4-6',
+      aliases: [],
+      models: [
+        { id: 'claude-opus-4-8',           label: 'Opus 4.8',   tier: 'premium'  },
+        { id: 'claude-sonnet-4-6',         label: 'Sonnet 4.6', tier: 'standard', default: true },
+        { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5',  tier: 'fast'     },
+      ],
+    },
+    openai: {
+      displayName: 'OpenAI API',
+      default: 'gpt-4.1',
+      aliases: [],
+      models: [
+        { id: 'gpt-4.1', label: 'GPT-4.1', tier: 'premium', default: true },
+        { id: 'gpt-4o',  label: 'GPT-4o',  tier: 'standard' },
+        { id: 'o4-mini', label: 'o4-mini', tier: 'fast' },
+        { id: 'o3-mini', label: 'o3-mini', tier: 'fast' },
+      ],
+    },
+  },
+};

package/lib/chat/tool-dispatcher.ts

@@ -189,6 +189,25 @@ const BUILTINS: Record<string, BuiltinHandler> = {
     return line;
   },
 
+  // Query a pipeline run's status + per-node results by id (pairs with
+  // trigger_pipeline's returned id). Mirrors the MCP get_pipeline_status tool.
+  get_pipeline_status: async (input) => {
+    const params = (input as { pipeline_id?: string } | undefined) || {};
+    if (!params.pipeline_id) return 'get_pipeline_status failed: pipeline_id is required (returned by trigger_pipeline).';
+    const { getPipeline } = await import('../pipeline');
+    const pipeline = getPipeline(params.pipeline_id);
+    if (!pipeline) return `Pipeline "${params.pipeline_id}" not found.`;
+    const nodes = Object.entries(pipeline.nodes || {}).map(([id, n]) => {
+      let line = `  ${id}: ${n.status}`;
+      if (n.error) line += ` — ${n.error}`;
+      for (const [k, v] of Object.entries(n.outputs || {})) {
+        line += `\n    ${k}: ${String(v).slice(0, 200)}`;
+      }
+      return line;
+    }).join('\n');
+    return `Pipeline ${pipeline.id} [${pipeline.status}] (${pipeline.workflowName})\n${nodes}`;
+  },
+
   // Surface Forge's local context (projects + agents + skills) so the chat
   // agent can pick valid values for inputs like trigger_pipeline.input.project
   // without guessing. Cheap call — read-only directory + DB lookups.
@@ -291,6 +310,20 @@ export const BUILTIN_TOOL_DEFS: BuiltinToolDef[] = [
       },
     },
   },
+  {
+    name: 'get_pipeline_status',
+    description: "Check a Forge pipeline run's live status + per-node results by id. Pass pipeline_id (returned by trigger_pipeline) to get the run's overall status + each node's status / error / outputs. Use whenever the user asks how a running or finished pipeline is doing.",
+    input_schema: {
+      type: 'object',
+      properties: {
+        pipeline_id: {
+          type: 'string',
+          description: 'Pipeline run id (returned by trigger_pipeline).',
+        },
+      },
+      required: ['pipeline_id'],
+    },
+  },
   {
     name: 'list_forge_context',
     description: "Return the current Forge instance's local context: project names (use these as input.project for pipelines / dispatch_task), agent profile ids, and installed skills. Call this whenever the user references a project / agent / skill by name and you need to validate the name OR when picking defaults for trigger_pipeline / dispatch_task. No arguments.",

package/lib/help-docs/05-pipelines.md

@@ -639,6 +639,15 @@ stop_condition: "all agents say DONE"
 initial_prompt: "Review PR #{{input.pr_number}} in project {{input.project}}. Reviewer: analyze the diff. Author: be ready to address feedback."
 ```
 
+## Controlling pipelines from chat
+
+The chat assistant has builtin tools for pipelines, so you can run and check them in plain language:
+
+- **`trigger_pipeline`** — start a workflow. Ask the assistant to "run the `<name>` pipeline" and it dispatches the run, returning a pipeline run id. Call it with no arguments first and it lists every workflow plus its input schema.
+- **`get_pipeline_status`** — check a run by id. Ask "what's the status of pipeline `<id>`?" and it returns the run's overall status plus each node's status, error, and outputs.
+
+Typical flow: trigger a pipeline, note the returned id, then ask the assistant for its status whenever you want an update — no need to open the Pipelines view. The same two tools are exposed to Claude Code over MCP (`trigger_pipeline` / `get_pipeline_status`).
+
 ## Pipeline Model
 
 In **Settings → Pipeline Model**, you can select which Claude model runs pipeline tasks. Set to `default` to use the same model as regular tasks.

package/lib/public-info/fetch.ts

@@ -0,0 +1,116 @@
+/**
+ * Generic fetch+cache helper for `forge-public-info` resources.
+ *
+ * Pattern: GitHub-hosted JSON files live under
+ *   `<publicInfoRepoUrl>/<resourceDir>/<file>.json`
+ *
+ * On read:
+ *   1. If a fresh cached copy exists (< TTL), return it.
+ *   2. Otherwise fetch from the configured `publicInfoRepoUrl`.
+ *   3. On any error (offline, 4xx, malformed JSON), return the bundled
+ *      fallback so the UI never breaks.
+ *
+ * Cache lives at `<dataDir>/public-info-cache/<resource>.json`. Each
+ * file has a sidecar `<resource>.meta.json` carrying the fetch
+ * timestamp; we don't trust HTTP `Last-Modified` because GitHub raw
+ * serves through a CDN that strips it.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '../dirs';
+import { loadSettings } from '../settings';
+
+const DEFAULT_REPO_URL = 'https://raw.githubusercontent.com/aiwatching/forge-public-info/main';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+interface CacheMeta { fetchedAt: number; etag?: string }
+
+function cacheDir(): string {
+  const dir = join(getDataDir(), 'public-info-cache');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function repoUrl(): string {
+  return (loadSettings() as any).publicInfoRepoUrl || DEFAULT_REPO_URL;
+}
+
+function cacheKey(resourcePath: string): string {
+  // public/info/models/registry.json → models-registry
+  return resourcePath.replace(/\.json$/, '').replace(/[^a-zA-Z0-9]/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function readCache(resourcePath: string): { data: unknown; meta: CacheMeta } | null {
+  const key = cacheKey(resourcePath);
+  const dataPath = join(cacheDir(), `${key}.json`);
+  const metaPath = join(cacheDir(), `${key}.meta.json`);
+  if (!existsSync(dataPath) || !existsSync(metaPath)) return null;
+  try {
+    return {
+      data: JSON.parse(readFileSync(dataPath, 'utf-8')),
+      meta: JSON.parse(readFileSync(metaPath, 'utf-8')),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(resourcePath: string, data: unknown): void {
+  const key = cacheKey(resourcePath);
+  try {
+    writeFileSync(join(cacheDir(), `${key}.json`), JSON.stringify(data, null, 2), 'utf-8');
+    writeFileSync(
+      join(cacheDir(), `${key}.meta.json`),
+      JSON.stringify({ fetchedAt: Date.now() } satisfies CacheMeta, null, 2),
+      'utf-8',
+    );
+  } catch (err) {
+    console.warn('[public-info] cache write failed:', err instanceof Error ? err.message : err);
+  }
+}
+
+/**
+ * Fetch a public-info resource with built-in cache + fallback.
+ *
+ * @param resourcePath  Path under the repo, e.g. `"models/registry.json"`
+ * @param fallback      Used when network + cache both fail
+ * @param opts.forceRefresh  Skip cache TTL check (e.g., user-triggered refresh)
+ */
+export async function fetchPublicInfo<T>(
+  resourcePath: string,
+  fallback: T,
+  opts: { forceRefresh?: boolean } = {},
+): Promise<T> {
+  const now = Date.now();
+
+  // 1. Cache hit (fresh)
+  if (!opts.forceRefresh) {
+    const cached = readCache(resourcePath);
+    if (cached && now - cached.meta.fetchedAt < CACHE_TTL_MS) {
+      return cached.data as T;
+    }
+  }
+
+  // 2. Network fetch
+  const url = `${repoUrl()}/${resourcePath}`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (res.ok) {
+      const data = await res.json();
+      writeCache(resourcePath, data);
+      return data as T;
+    }
+    console.warn(`[public-info] ${url} returned HTTP ${res.status}, using fallback`);
+  } catch (err) {
+    console.warn(`[public-info] ${url} fetch failed:`, err instanceof Error ? err.message : err);
+  }
+
+  // 3. Stale cache (better than fallback)
+  const cached = readCache(resourcePath);
+  if (cached) return cached.data as T;
+
+  // 4. Bundled fallback
+  return fallback;
+}

package/lib/public-info/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Shapes of JSON resources served from the public-info repo
+ * (https://github.com/aiwatching/forge-public-info, by default).
+ *
+ * Each resource lives under `<repoUrl>/<resource-dir>/<file>.json` so new
+ * resource types can be added without touching settings. Forge fetches
+ * them via `lib/public-info/fetch.ts` (24h cache + built-in fallback).
+ */
+
+export interface ModelInfo {
+  id: string;
+  label: string;
+  /** Rough quality/cost band — used by UI to sort/group. */
+  tier?: 'premium' | 'standard' | 'fast';
+  default?: boolean;
+}
+
+export interface ModelAlias {
+  id: string;
+  label: string;
+}
+
+export interface AgentModels {
+  displayName: string;
+  default: string;
+  aliases: ModelAlias[];
+  models: ModelInfo[];
+}
+
+export interface ModelsRegistry {
+  version: number;
+  updatedAt: string;
+  note?: string;
+  /** Keyed by CLI type (e.g. `claude-code`, `codex`, `aider`). */
+  agents: Record<string, AgentModels>;
+  /** Keyed by API provider id (e.g. `anthropic`, `openai`, `grok`, `google`, `deepseek`, `litellm`). */
+  providers?: Record<string, AgentModels>;
+}

package/lib/public-info/use-models-registry.ts

@@ -0,0 +1,66 @@
+/**
+ * Client-side hook for the model registry. Lazy-fetches from
+ * `GET /api/public-info/models`, caches in module-level state so
+ * multiple components sharing the registry hit the network once per
+ * page load. Returns the bundled fallback shape until the network
+ * round-trip completes so callers never see `undefined`.
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+import { KNOWN_MODELS_FALLBACK } from '../agents/known-models';
+import type { ModelsRegistry, AgentModels } from './types';
+
+let cached: ModelsRegistry | null = null;
+let inflight: Promise<ModelsRegistry> | null = null;
+
+async function load(refresh = false): Promise<ModelsRegistry> {
+  if (cached && !refresh) return cached;
+  if (inflight && !refresh) return inflight;
+  inflight = (async () => {
+    try {
+      const res = await fetch(`/api/public-info/models${refresh ? '?refresh=1' : ''}`);
+      if (res.ok) {
+        const data = await res.json();
+        cached = data as ModelsRegistry;
+        return cached;
+      }
+    } catch {}
+    cached = KNOWN_MODELS_FALLBACK;
+    return cached;
+  })();
+  try { return await inflight; } finally { inflight = null; }
+}
+
+export function useModelsRegistry(): {
+  registry: ModelsRegistry;
+  refresh: () => Promise<void>;
+  loading: boolean;
+} {
+  const [registry, setRegistry] = useState<ModelsRegistry>(cached ?? KNOWN_MODELS_FALLBACK);
+  const [loading, setLoading] = useState(!cached);
+
+  useEffect(() => {
+    if (cached) return;
+    setLoading(true);
+    load().then(r => { setRegistry(r); setLoading(false); });
+  }, []);
+
+  async function refresh() {
+    setLoading(true);
+    const r = await load(true);
+    setRegistry(r);
+    setLoading(false);
+  }
+
+  return { registry, refresh, loading };
+}
+
+/** Get the model option list for a specific agent CLI type. Returns the
+ *  flat list of `[...aliases, ...models]` as the picker expects them. */
+export function pickerOptions(registry: ModelsRegistry, cliType: string): string[] {
+  const agent: AgentModels | undefined = registry.agents[cliType];
+  if (!agent) return ['default'];
+  return [...agent.aliases.map(a => a.id), ...agent.models.map(m => m.id)];
+}