Modes of Operation

The Bridge SDK supports a role matrix — who acts as PM, who acts as Coder, and whether operations are visible or silent. This gives true flexibility for different workflows.

The Role Matrix

Mode 1: Nity Standalone

Nity runs its own PM+Coder pipeline. No external client. Nity analyzes, plans, executes, validates, and reflects — all internally.

Nity (PM + Coder)
  └─→ TaskAnalyzer → StrategyPlanner → ExecutionRouter
        → QualityGates → SelfReflection

Use when: Running Nity directly. Testing. No external orchestration.

Mode 2: Nity as PM / Validator / Auditor to Other Clients

Nity is the PM that oversees other clients. Each client has its own LLM and API keys. Nity does NOT become their coder — Nity ensures their models are doing what they're asked.

Nity (PM / Validator / Auditor)
  │
  ├─ analyze task
  ├─ assign to client
  ├─ monitor execution
  ├─ validate output (quality gates)
  └─ approve or request changes
  │
  ├──→ Client A (own Claude + API key)
  ├──→ Client B (own GPT + API key)
  └──→ Client C (own model + API key)

Key distinction: Each client runs its own model with its own API keys. Nity doesn't touch their execution. Nity:

Analyzes the task (complexity, risk, category)
Assigns to the right client based on capability matching
Monitors execution progress
Validates output against quality gates
Audits results (approve / request changes / block)

Nity can also be a coder itself when a task is better suited for Nity's own execution pipeline (e.g., tasks requiring Nity's memory, episodes, or skill registry).

// Nity as PM — assigns task to Cursor, validates result
const analysis = await nity.analyze("Add OAuth2 login");
// → complexity: complex, risk: medium, recommended: Cursor (has Claude)
 
// Nity monitors Cursor's execution (Cursor uses its own Claude + key)
// Nity validates Cursor's output against quality gates
const verdict = await nity.validate(cursorResult);
// → APPROVE / REQUEST-CHANGES / BLOCKED

Mode 3: Nity as PM+Coder to Other Clients

Nity both orchestrates AND executes. Other clients are observers — they send tasks to Nity and receive complete results. Nity runs the full pipeline (analyze → plan → execute → quality gates → reflect) and clients see the output.

Client (Observer) ──sendTask()──→ Nity (PM + Coder)
                                        │
                                        ├─ analyze
                                        ├─ plan
                                        ├─ execute (Nity's own engine)
                                        ├─ validate (quality gates)
                                        └─ reflect
                                        │
Client ◄────── NityResult ──────────────┘

Use when: Client wants Nity's full capabilities without managing the pipeline. Kilo delegates a complex task and gets back a complete result with quality gates and reflection.

const session = await createNitySession({ costTier: 'hybrid' });
const result = await session.sendTask('execute', 'Add OAuth2 to the API');
// Nity runs its FULL pipeline internally
// result includes: output, qualityGatePassed, reflection, episodeId

Mode 4: Client as PM+Coder, Nity as Engine

Client commands Nity's tools directly. Client chooses which tool to invoke, when, and validates results. Nity is the execution engine — client has full control.

Client (PM + Coder) ──sendTask("nity_analyze")──→ Nity (engine)
Client (PM + Coder) ──sendTask("nity_execute")──→ Nity (engine)
Client (PM + Coder) ──sendTask("nity_quality_gate")──→ Nity (engine)

Use when: Advanced users want fine-grained control. Kilo orchestrates a multi-step workflow: analyze → execute → validate → reflect, choosing each step explicitly.

const session = await createNitySession({ costTier: 'free' });
 
// Client is PM — decides what to do step by step
const analysis = await session.sendTask('analyze', 'Review the auth module');
 
// Client is Coder — decides when to execute based on analysis
if (analysis.output.includes('complex')) {
  const result = await session.sendTask('execute', 'Refactor auth', context);
  const validation = await session.sendTask('validate', 'Check the refactored auth');
}

Mode 5: Client as PM, Nity as Coder

Client orchestrates (analyzes, plans, validates), Nity executes. Client is the PM, Nity is the coder.

Client (PM)
  ├─ analyze task
  ├─ plan strategy
  ├─ sendTask("nity_execute", ...) ──→ Nity (Coder)
  │                                        └─ implement
  ├─ validate result                          └─ quality gates
  └─ reflect                                  └─ self-reflection

Use when: Client (Kilo) has its own PM logic and uses Nity purely for execution with built-in quality checks.

// Kilo analyzes externally
const plan = "Step 1: Add JWT middleware. Step 2: Protect routes. Step 3: Test.";
 
// Kilo delegates execution to Nity
const result = await session.sendTask('execute', plan, {
  memory: { goal: 'Secure the API', discoveries: ['Use RS256'] }
});
// Nity executes WITH its quality gates and self-reflection

The Key Distinction: Mode 2

Mode 2 is unique. Nity doesn't replace other clients' models — Nity oversees them.

                    Nity (PM)
                   ┌─────────┐
                   │ Analyze │
                   │ Assign  │
                   │ Monitor │
                   │ Validate│
                   │ Audit   │
                   └────┬────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │  Cursor  │  │  VS Code │  │ QuantumReef│
    │ (Claude) │  │  (GPT)   │  │ (12 engines)│
    │ own keys │  │ own keys │  │  own keys  │
    └──────────┘  └──────────┘  └──────────┘

Each client:

Has its own LLM (Claude, GPT, Gemini, local models)
Has its own API keys
Runs its own execution
Produces its own output

Nity:

Analyzes the task before assignment
Routes to the best client based on capability matching
Monitors execution progress
Validates output against quality gates
Issues verdicts (APPROVE / REQUEST-CHANGES / BLOCKED)
Records episodes for future learning

Nity is the quality assurance layer that sits on top of multiple coding agents, ensuring consistent quality regardless of which model is executing.

Visibility

Each role can be combined with visibility:

Visibility	What Happens
`silent`	Operations happen internally. Natural-language responses only.
`visible`	Terminal window shows structured operations (tool calls, strategy plans, quality gates, verdicts).

When to Use Visible Mode

Learning: Watch how natural language maps to structured operations. Verification: Confirm intent matches execution. See Nity's routing decisions and quality verdicts. Ambiguity Detection: Catch misclassifications early. If Nity assigns to the wrong client or classifies wrong, you see it and redirect.

User: "Fix the login bug"
Visible terminal shows:
  TaskAnalyzer: category=debug, complexity=moderate, risk=low
  PM assigns to: Cursor (has Claude, good for debugging)
  ...
  Nity validates: quality gates PASS
  Nity verdict: APPROVE

Mode Selection

Natural Language

"Run Nity standalone"                    → Mode 1
"Nity as PM for these clients"           → Mode 2
"Delegate this to Nity fully"            → Mode 3
"I'll orchestrate, use Nity tools"       → Mode 4
"I'll plan, Nity executes"               → Mode 5
"Show me what Nity is doing"             → Any mode + visible
"Run silently"                           → Any mode + silent

Configuration

{
  "bridgeMode": "nity-pm",
  "bridgeVisibility": "visible",
  "costTier": "hybrid"
}

Use Cases by Mode

Mode	Best For	Who Controls	Who Executes
1. Standalone	Testing, direct use	Nity	Nity
2. Nity as PM	Multi-client QA	Nity (PM)	Other clients (own models)
3. Nity as PM+Coder	Delegation, simplicity	Nity	Nity
4. Client as PM+Coder	Fine-grained control	Client	Nity
5. Client as PM	Client has own PM logic	Client (PM)	Nity (Coder)

True flexibility. Nity adapts to the workflow. Whether Nity oversees other models, runs everything itself, or serves as an execution engine — the same SDK handles it all. The visible/silent toggle adds observability on top.

Session Registry Notification Channels