Phase 6: Data Flow Analysis

flowchart LR
    User["User Code"] -->|"prompt"| SDK["SDK Session"]
    SDK -->|"JSON-RPC request"| CLI["CLI Process"]
    CLI -->|"HTTP / API"| LLM["LLM Backend"]
    LLM -->|"streams response"| CLI
    CLI -->|"session.event notifications"| SDK
    SDK -->|"_dispatchEvent"| User
            

flowchart TD
    A["sendAndWait(prompt, timeout)"] --> B["Register idle/error listener"]
    B --> C["send(prompt) → session.send RPC"]
    C --> D["Events stream in: assistant.message..."]
    D --> E{"session.idle received?"}
    E -->|"Yes"| F["Resolve with lastAssistantMessage"]
    E -->|"Timeout"| G["Reject with TimeoutError"]
            

flowchart LR
    A["User Code"] <-->|"calls"| B["SDK\nMessageConnection / JsonRpcClient"]
    B <-->|"stdio (default)\nor TCP"| C["CLI Process"]
            

flowchart TD
    A["createSession(config)"] --> B["Validate config"]
    B --> C["Auto-start client if not connected"]
    C --> D["Generate sessionId (UUID v4)"]
    D --> E["Create CopilotSession object\nRegister tools, permissions, hooks\nsessions.set(sessionId, session)"]
    E --> F["sendRequest 'session.create' → CLI"]
    F --> G["CLI initializes context, model, tools, MCP"]
    G --> H["Store workspacePath on session"]
    H --> I["Return session to caller"]
    style E fill:#22C55E,color:#0F172A,stroke:#22C55E
            

flowchart TD
    A["session.disconnect()"] --> B["sendRequest session.destroy, sessionId\nCLI releases in-memory resources\ndisk preserved"]
    B --> C["Clear eventHandlers,\ntoolHandlers, permissionHandler"]
            

flowchart TD
    A["client.deleteSession(sessionId)"] --> B["sendRequest session.delete, sessionId\nCLI deletes all disk data"]
    B --> C["Remove session from\nclient.sessions map"]
            

flowchart TD
    A["client.stop()"] --> B["For each session: session.disconnect()\nTS: 3 retries, exponential backoff"]
    B --> C["Clear sessions map\nDispose JSON-RPC connection\nClear models cache"]
    C --> D["Close TCP socket if used\nKill CLI process if spawned\nstate = disconnected"]
            

flowchart LR
    A["CLI\nLLM generates tokens"] -->|"notification:\nsession.event"| B["SDK Client\nhandleSessionEventNotification\nsessions.get sessionId"]
    B --> C["Session\n_dispatchEvent\n_handleBroadcastEvent"]
    C --> D["User Code\nhandler event"]
            

flowchart LR
    A["Event 1: session.start\nparentId: null"] --> B["Event 2: user.message\nparentId: aaa"]
    B --> C["Event 3: assistant.turn_start"]
    C --> D["...\nEvent N: session.idle"]
            

sequenceDiagram
    participant CLI as CLI Server
    participant SDK as SDK Client
    participant Handler as Tool Handler
    CLI->>SDK: notification: external_tool.requested
    SDK->>Handler: handler(args, invocation)
    Handler-->>SDK: result
    SDK->>CLI: rpc: tools.handlePendingToolCall
    Note over CLI: Continues with tool result
            

sequenceDiagram
    participant CLI as CLI
    participant SDK as SDK
    participant Handler as Handler
    CLI->>SDK: request: tool.call
    Note over SDK: handleToolCallRequestV2<br/>session.getToolHandler(toolName)
    SDK->>Handler: handler(invocation)
    Handler-->>SDK: result
    SDK-->>CLI: response: textResultForLLM, resultType
            

flowchart TD
    A["User provides tools in SessionConfig:\ntools: name, description, parameters, handler"] --> B["Wire Payload"]
    A --> C["Local Registration"]
    B --> D["CLI receives:\ntools: name, desc, params\nno handlers"]
    C --> E["Session stores:\ntoolHandlers.set name, handler\nlocal only"]
            

sequenceDiagram
    participant CLI as CLI
    participant SDK as SDK
    participant Hook as User Hook
    CLI->>SDK: request: hooks.invoke(hookType, input)
    Note over SDK: _handleHooksInvoke<br/>handler = handlerMap[hookType]
    SDK->>Hook: handler(input, sessionId)
    Hook-->>SDK: result
    SDK-->>CLI: response: output
    Note over CLI: Applies hook output
            

sequenceDiagram
    participant CLI as CLI
    participant SDK as SDK
    participant Handler as User Handler
    CLI->>SDK: notification: session.event<br/>permission.requested
    Note over SDK: _handleBroadcastEvent
    SDK->>Handler: permissionHandler(request, sessionId)
    Handler-->>SDK: kind: approved
    SDK->>CLI: rpc: permissions.handlePendingPermissionRequest<br/>requestId, result
    Note over CLI: Proceeds or aborts tool
            

sequenceDiagram
    participant CLI as CLI
    participant SDK as SDK
    CLI->>SDK: request: permission.request
    Note over SDK: handlePermissionRequestV2<br/>permissionHandler(request, sessionId)
    SDK-->>CLI: response: result kind
            

flowchart TD
    L4["Layer 4: Session Event Errors\nsession.error event: message, stack\nDelivered to event handlers, causes sendAndWait to reject"]
    L3["Layer 3: SDK Application Errors\nClient not connected | onPermissionRequest handler required\nprotocol version mismatch | CLI process exited with code N"]
    L2["Layer 2: JSON-RPC Protocol Errors\nResponseError with code/message\nTS: ResponseError, Py: JsonRpcError, Go: jsonrpc2.Error, C#: RemoteInvocationException"]
    L1["Layer 1: JSON-RPC Transport Errors\nConnection refused / broken pipe / timeout\nProcess exit before response"]
    L4 --- L3 --- L2 --- L1
            

flowchart TD
    A["client.start()\nstate = connecting"] --> B["startCLIServer()\nmay fail: CLI not found"]
    B --> C["connectToServer()\nmay fail: TCP connect error"]
    C --> D["verifyProtocolVersion()\nmay fail: version mismatch"]
    D --> E["state = connected\nor error on catch"]
            

flowchart TD
    A["User-Provided Options\nCopilotClientOptions\ncliPath, cliUrl, useStdio, port, cwd,\nenv, githubToken, autoStart, logLevel, ..."] -->|"Validated and merged\nwith defaults"| B["client.options internal\nUsed during start to spawn CLI / connect"]
    B --> C["SessionConfig\nmodel, tools, systemMessage,\nprovider, hooks, mcpServers,\ncustomAgents, ..."]
    C -->|"Wire Payload\nsent to CLI"| D["Wire Payload: session.create RPC\nmodel, sessionId, clientName, reasoningEffort\ntools: name, desc, params - no handlers\nsystemMessage, provider, mcpServers\nrequestPermission: true, hooks: true/false\nworkingDirectory, streaming, customAgents"]
    C -->|"Local Registration\nkept in SDK"| E["Local Registration\nsession.registerTools\nsession.registerPermissionHandler\nsession.registerUserInputHandler\nsession.registerHooks\nsession.on onEvent"]
            

flowchart LR
    A["SDK Client Process\n\nCopilotClient: state, connection,\ncliProcess, socket, actualPort,\nmodelsCache, negotiatedProtocolVersion,\nsessions Map, lifecycleHandlers, options\n\nCopilotSession per session: sessionId,\nworkspacePath, connection ref,\neventHandlers, typedEventHandlers,\ntoolHandlers, permissionHandler,\nuserInputHandler, hooks, _rpc"]
    B["CLI Process\n\nConversation history persisted\nPlanning state\nTool registry built-in + SDK schemas\nModel state\nWorking directory / Git context\nMCP server connections\nAuthentication state\nSession workspace files"]
    A <-->|"JSON-RPC"| B
            

flowchart LR
    A["CopilotClient 1\nOwns connection, CLI process\nRoutes notifications by sessionId"] -->|"manages N"| B["CopilotSession N\nReferences same connection\nDispatches events to handlers\nExecutes tools locally"]