Merge pull request #85 from aaditagrawal/codex/sync-upstream-traits-and-fork-rules

fix(web): scope traits by provider instance

Author: aaditagrawal

AGENTS.md

@@ -6,6 +6,7 @@
 - **NEVER create PRs, push branches, post comments, or perform ANY write operation against `pingdotgg/t3code` or any upstream/third-party repo.**
 - **NEVER run `gh pr create` without `--repo aaditagrawal/t3code`.** Always explicitly target the fork.
 - **NEVER run `gh` write commands (pr create, issue create, pr comment, pr close, pr merge) against any repo other than `aaditagrawal/t3code`.**
+- Any request involving PRs, issues, GitHub Actions, workflows, checks, comments, labels, releases, or other GitHub repo operations is fork-only: use `aaditagrawal/t3code` explicitly and do not target upstream.
 - The ONLY interaction with upstream is `git fetch upstream` to pull changes. Everything else targets `origin` (the fork).
 - When merging upstream changes, create a PR on `aaditagrawal/t3code` targeting the fork's `main` branch.
 
@@ -14,23 +15,33 @@
 - The fork's `README.md` takes priority over upstream's. On merge conflicts, keep ours.
 - Do NOT commit scratch/analysis markdown files (e.g. `CONFLICT_ANALYSIS.md`, plan dumps) into the repo.
 
+## Protected Fork Features
+
+When syncing upstream, preserve these fork features unless the user explicitly asks to remove them:
+
+1. Multi-provider runtime support for the built-in drivers: Codex CLI, Claude Code, Cursor, Droid, OpenCode, Amp, Copilot, Gemini CLI, and Kilo.
+2. Usage and limit monitoring, including token/context usage snapshots, provider usage events, Codex account rate-limit streams, and the web rate-limit banner/panel UX.
+3. Provider management UX, including custom provider instances, per-instance environment/config/model state, custom model slugs, and provider-scoped traits such as reasoning, context window, fast mode, and agent selection.
+4. Provider-neutral orchestration reliability, including SQLite event persistence, command receipts, replay/live stream ordering, session restart/reconnect behavior, and projection consistency.
+
 ## Task Completion Requirements
 
 - All of `bun fmt`, `bun lint`, and `bun typecheck` must pass before considering tasks completed.
 - NEVER run `bun test`. Always use `bun run test` (runs Vitest).
 
 ## Project Snapshot
 
-T3 Code is a multi-provider web GUI for coding agents. It supports 8 providers:
+T3 Code is a multi-provider web GUI for coding agents. This fork supports 9 built-in provider drivers:
 
 - **Codex CLI** (v0.37.0+) — JSON-RPC over stdio
 - **Claude Code** — Claude Agent SDK with thinking tokens and permission modes
 - **Cursor** — ACP (Agent Communication Protocol) over stdio
+- **Droid** — Factory Droid SDK runtime
+- **OpenCode** — SDK CLI server
 - **Copilot** — GitHub Copilot CLI
 - **Gemini CLI** — Google Gemini CLI with persistent JSON
 - **Amp** — Amp Code headless mode (no `/mode free`)
 - **Kilo** — HTTP SSE transport
-- **OpenCode** — SDK CLI server
 
 This repository is a VERY EARLY WIP. Proposing sweeping changes that improve long-term maintainability is encouraged.
 

CLAUDE.md

@@ -1 +1 @@
-AGENTS.md
+AGENTS.md

CONTRIBUTING.md

@@ -2,7 +2,16 @@
 
 First off, thank you for considering contributing to this fork! It's people like you that make the open-source community such an amazing place to learn, inspire, and create.
 
-This fork is maintained in [aaditagrawal/t3code](https://github.com/aaditagrawal/t3code) and focuses on expanding provider support while improving the core orchestration and persistence layers.
+This fork is maintained in [aaditagrawal/t3code](https://github.com/aaditagrawal/t3code) and focuses on expanding provider support, preserving usage and limit monitoring, and improving the core orchestration and persistence layers.
+
+## Protected Fork Features
+
+Pull requests and upstream syncs should preserve these four fork features unless the change explicitly replaces them with equivalent or better behavior:
+
+1. Multi-provider runtime support across Codex CLI, Claude Code, Cursor, Droid, OpenCode, Amp, Copilot, Gemini CLI, and Kilo.
+2. Usage and limit monitoring, including token/context usage, provider usage events, and rate-limit UI.
+3. Provider management UX for custom instances, per-instance config/environment/model state, and provider-scoped traits.
+4. Provider-neutral orchestration reliability for persistence, replay/live ordering, reconnects, restarts, and projections.
 
 ## How Can I Contribute?
 

README.md

@@ -2,29 +2,33 @@
 
 T3 Code is a minimal web GUI for coding agents made by [Pingdotgg](https://github.com/pingdotgg). This project is a downstream fork of the original [T3 Code](https://github.com/pingdotgg/t3code), maintained in [aaditagrawal/t3code](https://github.com/aaditagrawal/t3code).
 
-This fork focuses on expanding provider support, improving persistence layers, and refining provider management across the app.
+This fork focuses on expanding provider support, keeping usage and limit monitoring visible, improving persistence layers, and refining provider management across the app.
 
-It supports Codex, Claude Code, Cursor, Copilot, Gemini CLI, Amp, Kilo, and OpenCode.
+It supports Codex, Claude Code, Cursor, Droid, OpenCode, Copilot, Gemini CLI, Amp, and Kilo.
 
 (NOTE: Amp /mode free is not supported, as Amp Code doesn't support it in headless mode - since they need to show ads for that business model to work.)
 
 ## Why this fork?
 
-This fork aims to provide a more robust and feature-rich multi-provider experience, with improved server management, more reliable persistence of orchestration events, and UI refinements for settings and model selection.
+This fork aims to provide a more robust and feature-rich multi-provider experience, with improved server management, visible usage/rate-limit monitoring, more reliable persistence of orchestration events, and UI refinements for settings and model selection.
+
+The protected fork features are multi-provider runtime support, usage and limit monitoring, provider management UX, and provider-neutral orchestration reliability. Upstream syncs should preserve those unless a change explicitly replaces them with equivalent or better behavior.
 
 ### Multi-provider support (Enhanced)
 
 Adds full provider adapters (server managers, service layers, runtime layers) for agents that are not yet on the upstream roadmap:
 
-| Provider    | What's included                                                           |
-| ----------- | ------------------------------------------------------------------------- |
-| Gemini CLI  | **Enhanced:** Adapter + `geminiCliServerManager` with full test coverage  |
-| Amp         | Adapter + `ampServerManager` for headless Amp sessions                    |
-| Copilot     | Adapter + CLI binary resolution + text generation layer                   |
-| Cursor      | Adapter + ACP probe integration + usage tracking                          |
-| Kilo        | Adapter + `kiloServerManager` + OpenCode-style server URL config          |
-| OpenCode    | Adapter + `opencodeServerManager` with hostname/port/workspace config     |
-| Claude Code | Full adapter with permission mode, thinking token limits, and SDK typings |
+| Provider       | What's included                                                           |
+| -------------- | ------------------------------------------------------------------------- |
+| Codex CLI      | App-server JSON-RPC support with usage/rate-limit monitoring              |
+| Claude Code    | Full adapter with permission mode, thinking token limits, and SDK typings |
+| Cursor         | ACP adapter, probe integration, permissions, and usage tracking           |
+| Droid          | Factory Droid SDK runtime integration                                     |
+| OpenCode       | Adapter with hostname/port/workspace config                               |
+| Amp            | Adapter + `ampServerManager` for headless Amp sessions                    |
+| GitHub Copilot | Adapter + CLI binary resolution + text generation layer                   |
+| Gemini CLI     | **Enhanced:** Adapter + `geminiCliServerManager` with full test coverage  |
+| Kilo           | Adapter + `kiloServerManager` + OpenCode-style server URL config          |
 
 ### Persistence & Orchestration Improvements
 
@@ -43,6 +47,7 @@ Adds full provider adapters (server managers, service layers, runtime layers) fo
 | Sidebar search      | Normalized thread title search with instant filtering                                      |
 | Plan sidebar        | Dedicated panel for reviewing, downloading, or saving proposed agent plans                 |
 | Terminal drawer     | Theme-aware integrated terminal with accent color styling                                  |
+| Usage monitoring    | Context window meter, token usage events, and account rate-limit banner/panel visibility   |
 
 ## Getting started
 
@@ -78,6 +83,7 @@ bun run dev
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
 - [Claude Code](https://github.com/anthropics/claude-code)
 - [Cursor](https://cursor.sh)
+- [Droid](https://factory.ai)
 - [Codex CLI](https://github.com/openai/codex) (requires v0.37.0 or later)
 - [Copilot](https://github.com/features/copilot)
 - [Amp](https://ampcode.com)

apps/web/src/components/chat/ChatComposer.tsx

@@ -703,9 +703,16 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         model: selectedModel,
         models: selectedProviderModels,
         prompt,
-        modelOptions: composerModelOptions?.[selectedProvider],
+        modelOptions: composerModelOptions?.[selectedInstanceId],
       }),
-    [composerModelOptions, prompt, selectedModel, selectedProvider, selectedProviderModels],
+    [
+      composerModelOptions,
+      prompt,
+      selectedInstanceId,
+      selectedModel,
+      selectedProvider,
+      selectedProviderModels,
+    ],
   );
 
   const selectedPromptEffort = composerProviderState.promptEffort;
@@ -994,21 +1001,23 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
 
   const providerTraitsMenuContent = renderProviderTraitsMenuContent({
     provider: selectedProvider,
+    instanceId: selectedInstanceId,
     ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
     ...(routeKind === "draft" && draftId ? { draftId } : {}),
     model: selectedModel,
     models: selectedProviderModels,
-    modelOptions: composerModelOptions?.[selectedProvider],
+    modelOptions: composerModelOptions?.[selectedInstanceId],
     prompt,
     onPromptChange: setPromptFromTraits,
   });
   const providerTraitsPicker = renderProviderTraitsPicker({
     provider: selectedProvider,
+    instanceId: selectedInstanceId,
     ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
     ...(routeKind === "draft" && draftId ? { draftId } : {}),
     model: selectedModel,
     models: selectedProviderModels,
-    modelOptions: composerModelOptions?.[selectedProvider],
+    modelOptions: composerModelOptions?.[selectedInstanceId],
     prompt,
     onPromptChange: setPromptFromTraits,
   });

apps/web/src/components/chat/TraitsPicker.tsx

@@ -1,5 +1,6 @@
 import {
   type ProviderDriverKind,
+  type ProviderInstanceId,
   type ProviderOptionDescriptor,
   type ProviderOptionSelection,
   type ScopedThreadRef,
@@ -196,6 +197,7 @@ export function shouldRenderTraitsControls(input: {
 
 export interface TraitsMenuContentProps {
   provider: ProviderDriverKind;
+  instanceId?: ProviderInstanceId;
   models: ReadonlyArray<ServerProviderModel>;
   model: string | null | undefined;
   prompt: string;
@@ -208,6 +210,7 @@ export interface TraitsMenuContentProps {
 
 export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
   provider,
+  instanceId,
   models,
   model,
   prompt,
@@ -228,11 +231,12 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
         return;
       }
       setProviderModelOptions(threadTarget, provider, nextOptions, {
+        ...(instanceId ? { instanceId } : {}),
         model,
         persistSticky: true,
       });
     },
-    [model, persistence, provider, setProviderModelOptions],
+    [instanceId, model, persistence, provider, setProviderModelOptions],
   );
   const {
     descriptors,
@@ -343,6 +347,7 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
 
 export const TraitsPicker = memo(function TraitsPicker({
   provider,
+  instanceId,
   models,
   model,
   prompt,
@@ -431,6 +436,7 @@ export const TraitsPicker = memo(function TraitsPicker({
       <MenuPopup align="start">
         <TraitsMenuContent
           provider={provider}
+          {...(instanceId ? { instanceId } : {})}
           models={models}
           model={model}
           prompt={prompt}

apps/web/src/components/chat/composerProviderState.tsx

@@ -1,5 +1,6 @@
 import {
   type ProviderDriverKind,
+  type ProviderInstanceId,
   type ProviderOptionSelection,
   type ScopedThreadRef,
   type ServerProviderModel,
@@ -35,6 +36,7 @@ export type ComposerProviderState = {
 
 type TraitsRenderInput = {
   provider: ProviderDriverKind;
+  instanceId?: ProviderInstanceId;
   threadRef?: ScopedThreadRef;
   draftId?: DraftId;
   model: string;
@@ -76,8 +78,17 @@ function renderTraitsControl(
   Component: typeof TraitsMenuContent | typeof TraitsPicker,
   input: TraitsRenderInput,
 ): ReactNode {
-  const { provider, threadRef, draftId, model, models, modelOptions, prompt, onPromptChange } =
-    input;
+  const {
+    provider,
+    instanceId,
+    threadRef,
+    draftId,
+    model,
+    models,
+    modelOptions,
+    prompt,
+    onPromptChange,
+  } = input;
   const hasTarget = threadRef !== undefined || draftId !== undefined;
   if (
     !hasTarget ||
@@ -88,6 +99,7 @@ function renderTraitsControl(
   return (
     <Component
       provider={provider}
+      {...(instanceId ? { instanceId } : {})}
       models={models}
       {...(threadRef ? { threadRef } : {})}
       {...(draftId ? { draftId } : {})}

apps/web/src/composerDraftStore.test.ts

@@ -21,6 +21,7 @@ import { createModelSelection } from "@t3tools/shared/model";
 // `stickyModelSelectionByProvider` maps are keyed by `ProviderInstanceId`
 // in production; these aliases keep the legacy-key migration tests concise.
 const CODEX_INSTANCE = ProviderInstanceId.make("codex");
+const CODEX_SECONDARY_INSTANCE = ProviderInstanceId.make("codex_secondary");
 const CLAUDE_AGENT_INSTANCE = ProviderInstanceId.make("claudeAgent");
 const CURSOR_INSTANCE = ProviderInstanceId.make("cursor");
 const CODEX_DRIVER = ProviderDriverKind.make("codex");
@@ -1201,6 +1202,43 @@ describe("composerDraftStore modelSelection", () => {
     );
   });
 
+  it("stores provider option changes on a selected custom instance", () => {
+    const store = useComposerDraftStore.getState();
+
+    store.setProviderModelOptions(
+      threadRef,
+      CODEX_DRIVER,
+      toSelections({ reasoningEffort: "low" }),
+      {
+        instanceId: CODEX_SECONDARY_INSTANCE,
+        model: "gpt-5-codex",
+        persistSticky: true,
+      },
+    );
+
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CODEX_SECONDARY_INSTANCE],
+    ).toEqual(
+      expect.objectContaining({
+        instanceId: CODEX_SECONDARY_INSTANCE,
+        options: [{ id: "reasoningEffort", value: "low" }],
+      }),
+    );
+    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.activeProvider).toBe(CODEX_SECONDARY_INSTANCE);
+    expect(useComposerDraftStore.getState().stickyActiveProvider).toBe(CODEX_SECONDARY_INSTANCE);
+    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider[CODEX_INSTANCE]).toBe(
+      undefined,
+    );
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CODEX_SECONDARY_INSTANCE],
+    ).toEqual(
+      expect.objectContaining({
+        instanceId: CODEX_SECONDARY_INSTANCE,
+        options: [{ id: "reasoningEffort", value: "low" }],
+      }),
+    );
+  });
+
   it("updates only the draft when sticky persistence is disabled", () => {
     const store = useComposerDraftStore.getState();
 

apps/web/src/composerDraftStore.ts

@@ -371,6 +371,7 @@ interface ComposerDraftStoreState {
     provider: ProviderDriverKind,
     nextProviderOptions: ReadonlyArray<ProviderOptionSelection> | null | undefined,
     options?: {
+      instanceId?: ProviderInstanceId | null | undefined;
       model?: string | null | undefined;
       persistSticky?: boolean;
     },
@@ -2456,7 +2457,7 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
           if (normalizedProvider === null) {
             return;
           }
-          const instanceKey = defaultInstanceIdForDriver(normalizedProvider);
+          const instanceKey = options?.instanceId ?? defaultInstanceIdForDriver(normalizedProvider);
           const fallbackModel =
             normalizeModelSlug(options?.model, normalizedProvider) ??
             DEFAULT_MODEL_BY_PROVIDER[normalizedProvider] ??
@@ -2501,7 +2502,9 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
                 const { options: _, ...rest } = stickyBase;
                 nextStickyMap[instanceKey] = rest as ModelSelection;
               }
-              nextStickyActiveProvider = base.activeProvider ?? instanceKey;
+              nextStickyActiveProvider = options.instanceId
+                ? instanceKey
+                : (base.activeProvider ?? instanceKey);
             }
 
             if (
@@ -2514,6 +2517,7 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
 
             const nextDraft: ComposerThreadDraftState = {
               ...base,
+              ...(options?.instanceId ? { activeProvider: instanceKey } : {}),
               modelSelectionByProvider: nextMap,
             };
             const nextDraftsByThreadKey = { ...state.draftsByThreadKey };

docs/custom-alpha-workflow.md

@@ -195,6 +195,13 @@ git fetch upstream
 git merge --ff-only upstream/main
 ```
 
+Before accepting upstream removals or resolving conflicts, verify the protected fork features still work:
+
+1. Multi-provider runtime support for Codex CLI, Claude Code, Cursor, Droid, OpenCode, Amp, Copilot, Gemini CLI, and Kilo.
+2. Usage and limit monitoring for token/context usage, provider usage events, and account rate-limit UI.
+3. Provider management UX for custom instances, per-instance config/environment/model state, and provider-scoped traits.
+4. Provider-neutral orchestration reliability for persistence, replay/live ordering, reconnects, restarts, and projections.
+
 Then refresh the alpha branch:
 
 ```bash