[BUG] Subagent launches consume 1 premium request each

[bizzkoot]

Bug Report

Summary

When any subagent is launched via the Task tool, it consumes 1 premium request. This is unexpected behavior since subagents are internal operations that should not consume user's premium quota.

Expected Behavior

• Only the main agent's initial user prompt should consume 1 premium request
• Subagent launches and operations should NOT consume additional premium requests

Actual Behavior

• Every subagent launch consumes 1 premium request
• This causes quota exhaustion to occur significantly faster when using subagent-based features

Environment

• CodeNomad version: latest
• Platform: All (Electron app)

Steps to Reproduce

1. Send a prompt to the main agent that will trigger a subagent
2. Observe the premium request count increases by 1 for the main agent
3. Observe the premium request count increases by ANOTHER 1 when the subagent is launched
4. Total: 2+ premium requests instead of expected 1

Root Cause Analysis

Based on code review, there is already a fix in place in packages/ui/src/stores/message-v2/instance-store.ts:

function updateUsageWithInfo(info: MessageInfo | undefined) {
  // ...
  const session = state.sessions[info.sessionID]
  if (session?.parentId != null) {
    if (import.meta.env.DEV) {
      console.log(`[Usage Debug] ⏭️ SKIPPING subagent session ${info.sessionID} - parentId: ${session.parentId}`)
    }
    return  // Skip usage tracking for subagents
  }
  // Track usage for main sessions
}

However, the issue may be that:

1. The Task tool completion in the MAIN session might be generating an assistant message that IS tracked
2. Or there's a timing issue where session.parentId is not yet populated when usage is tracked
3. Or the session hydration (rebuildUsageStateFromInfos) is not properly filtering subagent messages

Relevant Files

• packages/ui/src/stores/message-v2/instance-store.ts (lines 367-391)
• packages/server/src/workspaces/instance-events.ts (session cache with parentID)
• tasks/done/prd-subagent-premium-fix.md (PRD for the fix)

Investigation Needed

1. Verify that session.parentId is being set correctly before message.updated events
2. Check if tool completions in the main session are being incorrectly tracked
3. Add debug logging to trace when and where premium requests are being counted
4. Verify rebuildUsageStateFromInfos is properly filtering during hydration

Priority

High - This affects all users and causes significant quota waste

Labels

bug, premium, subagent, priority:high

[bizzkoot]

Deep Root Cause Analysis

After conducting an in-depth analysis using sequential thinking, I've identified the root cause of why subagent launches continue to consume 1 premium request each despite the implemented fix.

The Bug

Location: packages/server/src/workspaces/instance-events.ts (lines 213-248)

Root Cause: Caching Issue

The bug occurs due to a caching issue in the server-side event handler:

1. Subagent session is created in OpenCode instance
2. session.updated event arrives (may or may NOT include parentID field from OpenCode)
3. Server caches the session at line 219 with whatever parentID value was in the event (possibly null or undefined)
4. message.updated event arrives for the subagent's response
5. Server checks cache at line 229 - finds the session (with potentially WRONG parentID)
6. No synthetic event emitted because session is already cached
7. UI receives message.updated event without ever receiving a correct session.updated with parentID
8. UI tracks usage because session.parentId is null/undefined (appears to be a main session)

The Fix (Recommended)

Modify packages/server/src/workspaces/instance-events.ts (lines 225-245) to always fetch session info for message.updated events.

Key change: Remove the if (!cache.has(sessionId)) check and always fetch fresh session info to ensure correct parentID.

This ensures:

1. The cache always has the correct parentID from the source of truth
2. Synthetic session.updated events are emitted whenever parentID changes or is initially missing
3. The UI-side fix works correctly

---

Analyzed via sequential-thinking deep dive

[bizzkoot]

Regression Risk Analysis & Recommended Fix

Root Cause: Event Ordering Race Condition

The current updateUsageWithInfo function that checks session.parentId is CORRECT, but it fails due to a timing issue:

The Problem:

1. message.updated arrives BEFORE session.updated
2. First message finds no session in state.sessions
3. Falls through to track usage (the "safe fallback" behavior)
4. Premium is consumed
5. Later session.updated arrives with parentID - too late!

Proposed Fix: "Always Fetch" - Regression Risk: HIGH

If we call getSessionInfo() for EVERY message.updated:

• 10-50x increase in HTTP requests (each LLM response triggers 10-50 message events)
• Potential rate limiting issues
• Added latency per message
• API failures could cause inconsistent behavior

RECOMMENDED SOLUTION: Synchronous Event Ordering

Fix the event ordering WITHOUT performance impact:

// In instance-events.ts, message.updated handler
if (event.type === "message.updated") {
  const info = (event as any)?.properties?.info
  const sessionId = info?.sessionID
  if (typeof sessionId === "string") {
    const cache = this.getSessionCache(workspaceId)
    
    if (!cache.has(sessionId)) {
      const sessionInfo = await this.getSessionInfo(workspaceId, sessionId)
      if (sessionInfo && typeof sessionInfo.id === "string") {
        cache.set(sessionInfo.id, { parentID: sessionInfo.parentID ?? null })
        const syntheticEvent = {
          type: "session.updated",
          properties: { info: sessionInfo },
        }
        
        // CRITICAL: Process session.updated SYNCHRONOUSLY
        this.handleInstanceEvent(workspaceId, syntheticEvent)
      }
    }
  }
  
  // NOW publish message.updated (session guaranteed to exist)
  this.options.eventBus.publish({ type: "instance.event", instanceId: workspaceId, event })
  return
}

Why this works:

• Calls handleInstanceEvent() directly (synchronous)
• Ensures session is created BEFORE message.updated is published
• Only ONE HTTP request per session (first message only)
• Regression Risk: LOW

Testing Strategy

1. Add diagnostic logging to verify event ordering
2. Test with rapid subagent launches
3. Verify premium count doesn't increment
4. Check that message streaming isn't delayed